Loading...
Searching...
No Matches
casacore::RowBasedFile Class Reference

`#include <RowBasedFile.h>`

## Public Member Functions

| RowBasedFile ()=default
| RowBasedFile (const RowBasedFile &rhs)=delete
| RowBasedFile (RowBasedFile &&rhs) noexcept
| RowBasedFile (const std::string &filename, uint64_t header_size, uint64_t stride)
| Create or overwrite a new columnar file on disk.
| RowBasedFile (const std::string &filename, size_t header_size)
| Open an existing columnar file.
| ~RowBasedFile () noexcept
RowBasedFile & | operator= (RowBasedFile &&rhs)
void | Close ()
| Close the file.
void | Truncate (uint64_t n_rows)
void | Seek (off_t pos, int seek_direction)
void | ReadData (unsigned char *data, uint64_t size)
void | WriteData (const unsigned char *data, uint64_t size)
bool | IsOpen () const
uint64_t | DataLocation () const
| Offset of the first row in the file.
const std::string & | Filename () const
uint64_t | HeaderSize () const
| Number of bytes reserved for an optional header.
void | WriteHeader (const unsigned char *data)
| Write an optional extra header to the file.
void | ReadHeader (unsigned char *data)
| Read an optional extra header to the file.
uint64_t | NRows () const
| Total number of rows stored in this file.
void | SetNRows (uint64_t new_n_rows)
uint64_t | Stride () const
| Total number of bytes in one row.
void | SetStride (uint64_t new_stride)
| Set the number of bytes per row for this file.
void | AddRows (uint64_t n_rows)
| Adds a given number of rows to the back of the file.
void | DeleteRow ()
| Deletes the last row.

## Private Member Functions

void | CloseWithoutTruncate ()
void | WritePrivateHeader ()

## Static Private Member Functions

static std::string | ErrorStringHelper (int result_value, char *buffer)
static std::string | ErrorStringHelper (char *returned_buffer, char *)
static std::string | ErrorString ()

## Private Attributes

int | file_
| The "C" file API is used because we need to use (f)truncate, which is not available from the C++ fstream API.
uint32_t | private_header_size_
uint64_t | n_rows_
bool | need_truncate_
uint64_t | stride_
uint64_t | data_location_
| This variable is also used to set/calculate the header size, using the relation: data_location_ = private_header_size_ + header_size.
std::string | filename_

## Static Private Attributes

static constexpr uint32_t | kWriterPrivateHeaderSize
| The size of the private header that the writer creates for the current file format.
static constexpr uint32_t | kMagicFileTag
| First four bytes of a file.
static constexpr uint32_t | kFileVersion
| Version of this file, in format 0xaabb, where aa is the major version and bb is the minor version.

## Detailed Description

Definition at line 14 of file RowBasedFile.h.

## Constructor & Destructor Documentation

## RowBasedFile() [1/5]

casacore::RowBasedFile::RowBasedFile | ( |  | ) |

default

Referenced by operator=(), RowBasedFile(), RowBasedFile(), casacore::SimpleColumnarFile::SimpleColumnarFile(), casacore::SimpleColumnarFile::SimpleColumnarFile(), casacore::VarBufferedColumnarFile< 100 *1024 >::VarBufferedColumnarFile(), and casacore::VarBufferedColumnarFile< 100 *1024 >::VarBufferedColumnarFile().

## RowBasedFile() [2/5]

casacore::RowBasedFile::RowBasedFile | ( | const RowBasedFile & | rhs | ) |

delete

References RowBasedFile().

## RowBasedFile() [3/5]

casacore::RowBasedFile::RowBasedFile | ( | RowBasedFile && | rhs | ) |

inline noexcept

Definition at line 18 of file RowBasedFile.h.

References kWriterPrivateHeaderSize, and RowBasedFile().

## RowBasedFile() [4/5]

casacore::RowBasedFile::RowBasedFile | ( | const std::string & | filename,
|  | uint64_t | header_size,
|  | uint64_t | stride )

inline

Create or overwrite a new columnar file on disk.

Definition at line 38 of file RowBasedFile.h.

References data_location_, file_, filename_, kWriterPrivateHeaderSize, stride_, and WritePrivateHeader().

## RowBasedFile() [5/5]

casacore::RowBasedFile::RowBasedFile | ( | const std::string & | filename,
|  | size_t | header_size )

inline

Open an existing columnar file.

Combine reading of private header size, stride and user header size in one read call.

Definition at line 53 of file RowBasedFile.h.

References data_location_, file_, filename_, kFileVersion, kMagicFileTag, n_rows_, private_header_size_, ReadData(), and stride_.

## ~RowBasedFile()

casacore::RowBasedFile::~RowBasedFile | ( |  | ) |

inline noexcept

Definition at line 103 of file RowBasedFile.h.

References Close().

## Member Function Documentation

## AddRows()

void casacore::RowBasedFile::AddRows | ( | uint64_t | n_rows | ) |

inline

Adds a given number of rows to the back of the file.

Definition at line 232 of file RowBasedFile.h.

References NRows(), and SetNRows().

## Close()

void casacore::RowBasedFile::Close | ( |  | ) |

inline

Close the file.

After closing, all calls to I/O functions cause undefined behaviour, until the class is assigned to a new instance.

Truncate failed, still try to close the file to prevent a dangling open file, before throwing the exception.

Definition at line 126 of file RowBasedFile.h.

References CloseWithoutTruncate(), IsOpen(), need_truncate_, NRows(), and Truncate().

Referenced by casacore::VarBufferedColumnarFile< 100 *1024 >::Close(), operator=(), and ~RowBasedFile().

## CloseWithoutTruncate()

void casacore::RowBasedFile::CloseWithoutTruncate | ( |  | ) |

inline private

Definition at line 244 of file RowBasedFile.h.

References casacore::close(), data_location_, file_, filename_, kWriterPrivateHeaderSize, n_rows_, private_header_size_, and stride_.

Referenced by Close().

## DataLocation()

uint64_t casacore::RowBasedFile::DataLocation | ( |  | ) | const

inline

Offset of the first row in the file.

When using Seek() to move to a row, this number should be added to the offset.

Definition at line 177 of file RowBasedFile.h.

References data_location_.

Referenced by casacore::VarBufferedColumnarFile< 100 *1024 >::ActivateBlock(), casacore::SimpleColumnarFile::Read(), casacore::VarBufferedColumnarFile< 100 *1024 >::Read(), casacore::SimpleColumnarFile::ReadImplementation(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::WriteActiveBlock(), casacore::SimpleColumnarFile::WriteImplementation(), and casacore::VarBufferedColumnarFile< 100 *1024 >::~VarBufferedColumnarFile().

## DeleteRow()

void casacore::RowBasedFile::DeleteRow | ( |  | ) |

inline

Deletes the last row.

Definition at line 237 of file RowBasedFile.h.

References NRows(), and SetNRows().

## ErrorString()

std::string casacore::RowBasedFile::ErrorString | ( |  | ) |

inline static private

This is a small trick to allow both versions of strerror_r: by using function overloading, the right behaviour is picked.

Definition at line 319 of file RowBasedFile.h.

References ErrorStringHelper().

Referenced by Truncate().

## ErrorStringHelper() [1/2]

std::string casacore::RowBasedFile::ErrorStringHelper | ( | char * | returned_buffer,
|  | char * | )

inline static private

Definition at line 314 of file RowBasedFile.h.

## ErrorStringHelper() [2/2]

std::string casacore::RowBasedFile::ErrorStringHelper | ( | int | result_value,
|  | char * | buffer )

inline static private

Definition at line 307 of file RowBasedFile.h.

Referenced by ErrorString().

## Filename()

const std::string & casacore::RowBasedFile::Filename | ( |  | ) | const

inline

Definition at line 178 of file RowBasedFile.h.

References filename_.

## HeaderSize()

uint64_t casacore::RowBasedFile::HeaderSize | ( |  | ) | const

inline

Number of bytes reserved for an optional header.

Definition at line 182 of file RowBasedFile.h.

References data_location_, and private_header_size_.

Referenced by SetStride(), and WritePrivateHeader().

## IsOpen()

bool casacore::RowBasedFile::IsOpen | ( |  | ) | const

inline

Definition at line 172 of file RowBasedFile.h.

References file_.

Referenced by Close().

## NRows()

uint64_t casacore::RowBasedFile::NRows | ( |  | ) | const

inline

Total number of rows stored in this file.

Definition at line 203 of file RowBasedFile.h.

References n_rows_.

Referenced by AddRows(), Close(), and DeleteRow().

## operator=()

RowBasedFile & casacore::RowBasedFile::operator= | ( | RowBasedFile && | rhs | ) |

inline

Definition at line 109 of file RowBasedFile.h.

References Close(), data_location_, file_, filename_, n_rows_, need_truncate_, private_header_size_, RowBasedFile(), and stride_.

Referenced by casacore::SimpleColumnarFile::operator=(), and casacore::VarBufferedColumnarFile< 100 *1024 >::operator=().

## ReadData()

void casacore::RowBasedFile::ReadData | ( | unsigned char * | data,
|  | uint64_t | size )

inline

Definition at line 159 of file RowBasedFile.h.

References file_, filename_, casacore::read(), and casacore::size().

Referenced by casacore::VarBufferedColumnarFile< 100 *1024 >::ActivateBlock(), casacore::SimpleColumnarFile::Read(), casacore::VarBufferedColumnarFile< 100 *1024 >::Read(), ReadHeader(), casacore::SimpleColumnarFile::ReadImplementation(), and RowBasedFile().

## ReadHeader()

void casacore::RowBasedFile::ReadHeader | ( | unsigned char * | data | ) |

inline

Read an optional extra header to the file.

See also
  WriteHeader().

Definition at line 196 of file RowBasedFile.h.

References data_location_, private_header_size_, ReadData(), and Seek().

## Seek()

void casacore::RowBasedFile::Seek | ( | off_t | pos,
|  | int | seek_direction )

inline

Definition at line 152 of file RowBasedFile.h.

References file_, and filename_.

Referenced by casacore::VarBufferedColumnarFile< 100 *1024 >::ActivateBlock(), casacore::SimpleColumnarFile::Read(), casacore::VarBufferedColumnarFile< 100 *1024 >::Read(), ReadHeader(), casacore::SimpleColumnarFile::ReadImplementation(), SetStride(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::WriteActiveBlock(), WriteHeader(), casacore::SimpleColumnarFile::WriteImplementation(), and casacore::VarBufferedColumnarFile< 100 *1024 >::~VarBufferedColumnarFile().

## SetNRows()

void casacore::RowBasedFile::SetNRows | ( | uint64_t | new_n_rows | ) |

inline

Definition at line 205 of file RowBasedFile.h.

References n_rows_, and need_truncate_.

Referenced by AddRows(), DeleteRow(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::Write(), casacore::SimpleColumnarFile::WriteImplementation(), and casacore::VarBufferedColumnarFile< 100 *1024 >::WriteImplementation().

## SetStride()

void casacore::RowBasedFile::SetStride | ( | uint64_t | new_stride | ) |

inline

Set the number of bytes per row for this file.

This changes the format of the file, and because of this the file is emptied.

Definition at line 219 of file RowBasedFile.h.

References data_location_, HeaderSize(), kWriterPrivateHeaderSize, n_rows_, Seek(), stride_, Truncate(), and WritePrivateHeader().

Referenced by casacore::SimpleColumnarFile::SetStride(), and casacore::VarBufferedColumnarFile< 100 *1024 >::SetStride().

## Stride()

uint64_t casacore::RowBasedFile::Stride | ( |  | ) | const

inline

Total number of bytes in one row.

This value is also stored in the file, and is read from the file in OpenExisting().

Definition at line 214 of file RowBasedFile.h.

References stride_.

## Truncate()

void casacore::RowBasedFile::Truncate | ( | uint64_t | n_rows | ) |

inline

Definition at line 143 of file RowBasedFile.h.

References data_location_, ErrorString(), file_, filename_, n_rows_, and stride_.

Referenced by Close(), and SetStride().

## WriteData()

void casacore::RowBasedFile::WriteData | ( | const unsigned char * | data,
|  | uint64_t | size )

inline

Definition at line 166 of file RowBasedFile.h.

References file_, filename_, casacore::size(), and casacore::write().

Referenced by casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::Write(), casacore::VarBufferedColumnarFile< 100 *1024 >::WriteActiveBlock(), WriteHeader(), casacore::SimpleColumnarFile::WriteImplementation(), WritePrivateHeader(), and casacore::VarBufferedColumnarFile< 100 *1024 >::~VarBufferedColumnarFile().

## WriteHeader()

void casacore::RowBasedFile::WriteHeader | ( | const unsigned char * | data | ) |

inline

Write an optional extra header to the file.

When creating the file, the requested space is saved to store this header.

Parameters

  data | An array equal to the size of the header given in the CreateNew() and OpenExisting() calls.

Definition at line 189 of file RowBasedFile.h.

References data_location_, private_header_size_, Seek(), and WriteData().

## WritePrivateHeader()

void casacore::RowBasedFile::WritePrivateHeader | ( |  | ) |

inline private

Collect entire private header in one write call

Definition at line 256 of file RowBasedFile.h.

References HeaderSize(), kFileVersion, kMagicFileTag, kWriterPrivateHeaderSize, stride_, and WriteData().

Referenced by RowBasedFile(), and SetStride().

## Member Data Documentation

## data_location_

uint64_t casacore::RowBasedFile::data_location_

private

This variable is also used to set/calculate the header size, using the relation: data_location_ = private_header_size_ + header_size.

Definition at line 337 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), DataLocation(), HeaderSize(), operator=(), ReadHeader(), RowBasedFile(), RowBasedFile(), SetStride(), Truncate(), and WriteHeader().

## file_

int casacore::RowBasedFile::file_

private

The "C" file API is used because we need to use (f)truncate, which is not available from the C++ fstream API.

Definition at line 328 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), IsOpen(), operator=(), ReadData(), RowBasedFile(), RowBasedFile(), Seek(), Truncate(), and WriteData().

## filename_

std::string casacore::RowBasedFile::filename_

private

Definition at line 338 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), Filename(), operator=(), ReadData(), RowBasedFile(), RowBasedFile(), Seek(), Truncate(), and WriteData().

## kFileVersion

uint32_t casacore::RowBasedFile::kFileVersion

inline static constexpr private

Version of this file, in format 0xaabb, where aa is the major version and bb is the minor version.

The major version is checked against the version of the reader: if the file has a higher major version than the reader, the file is rejected. The minor version is not checked, thus an increase in minor version indicates a change in file format that is still readable by older readers.

Definition at line 305 of file RowBasedFile.h.

Referenced by RowBasedFile(), and WritePrivateHeader().

## kMagicFileTag

uint32_t casacore::RowBasedFile::kMagicFileTag

inline static constexpr private

First four bytes of a file.

This spells out "Crbf" when stored as a little endian number, which stands for "Casacore Row-based file". Files without this magic number in the first four bytes are rejected.

This also makes sure that a file written on a little endian machine is rejected by a big endian machine, and vice versa. Because big endian machines are extremely rare for astronomical processing, no effort is made to make it interchangable at this point of time. The official format is declared to use little endian numbers.

Definition at line 295 of file RowBasedFile.h.

Referenced by RowBasedFile(), and WritePrivateHeader().

## kWriterPrivateHeaderSize

uint32_t casacore::RowBasedFile::kWriterPrivateHeaderSize

inline static constexpr private

The size of the private header that the writer creates for the current file format.

This number is written into the file. Whenever a file is read, the number written into the file should be used to skip over the header. That way, members can be added to the header that can still be read by older readers. The header consists of:

- u32: "Crbf" (magic file tag)
- u32: file version
- u32: private header size
- u64: stride
- u64: full header size (private header + user header)

Definition at line 281 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), RowBasedFile(), RowBasedFile(), SetStride(), and WritePrivateHeader().

## n_rows_

uint64_t casacore::RowBasedFile::n_rows_

private

Definition at line 330 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), NRows(), operator=(), RowBasedFile(), SetNRows(), SetStride(), and Truncate().

## need_truncate_

bool casacore::RowBasedFile::need_truncate_

private

Definition at line 331 of file RowBasedFile.h.

Referenced by Close(), operator=(), and SetNRows().

## private_header_size_

uint32_t casacore::RowBasedFile::private_header_size_

private

Definition at line 329 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), HeaderSize(), operator=(), ReadHeader(), RowBasedFile(), and WriteHeader().

## stride_

uint64_t casacore::RowBasedFile::stride_

private

Definition at line 332 of file RowBasedFile.h.

Referenced by CloseWithoutTruncate(), operator=(), RowBasedFile(), RowBasedFile(), SetStride(), Stride(), Truncate(), and WritePrivateHeader().

The documentation for this class was generated from the following file:

- tables/AlternateMans/RowBasedFile.h