#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

◆ RowBasedFile() [2/5]

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

delete

◆ RowBasedFile() [3/5]

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

inlinenoexcept

Definition at line 18 of file RowBasedFile.h.

References kWriterPrivateHeaderSize.

◆ 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.

◆ 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_, kFileVersion, kMagicFileTag, n_rows_, private_header_size_, ReadData(), and stride_.

◆ ~RowBasedFile()

casacore::RowBasedFile::~RowBasedFile ( )

inlinenoexcept

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< BufferSize >::Close(), operator=(), and ~RowBasedFile().

◆ CloseWithoutTruncate()

void casacore::RowBasedFile::CloseWithoutTruncate ( )

inlineprivate

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< BufferSize >::ActivateBlock(), casacore::VarBufferedColumnarFile< BufferSize >::Read(), casacore::SimpleColumnarFile::Read(), casacore::SimpleColumnarFile::ReadImplementation(), casacore::VarBufferedColumnarFile< BufferSize >::Write(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< BufferSize >::WriteActiveBlock(), casacore::SimpleColumnarFile::WriteImplementation(), and casacore::VarBufferedColumnarFile< BufferSize >::~VarBufferedColumnarFile().

◆ DeleteRow()

void casacore::RowBasedFile::DeleteRow ( )

inline

Deletes the last row.

Definition at line 237 of file RowBasedFile.h.

References NRows(), and SetNRows().

◆ ErrorString()

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

inlinestaticprivate

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]

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

inlinestaticprivate

Definition at line 314 of file RowBasedFile.h.

◆ ErrorStringHelper() [2/2]

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

inlinestaticprivate

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_, and stride_.

Referenced by casacore::SimpleColumnarFile::operator=(), and casacore::VarBufferedColumnarFile< BufferSize >::operator=().

◆ ReadData()

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

inline

Definition at line 159 of file RowBasedFile.h.

References file_, and filename_.

Referenced by casacore::VarBufferedColumnarFile< BufferSize >::ActivateBlock(), casacore::VarBufferedColumnarFile< BufferSize >::Read(), casacore::SimpleColumnarFile::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< BufferSize >::ActivateBlock(), casacore::VarBufferedColumnarFile< BufferSize >::Read(), casacore::SimpleColumnarFile::Read(), ReadHeader(), casacore::SimpleColumnarFile::ReadImplementation(), SetStride(), casacore::VarBufferedColumnarFile< BufferSize >::Write(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< BufferSize >::WriteActiveBlock(), WriteHeader(), casacore::SimpleColumnarFile::WriteImplementation(), and casacore::VarBufferedColumnarFile< BufferSize >::~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::VarBufferedColumnarFile< BufferSize >::Write(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< BufferSize >::WriteImplementation(), and casacore::SimpleColumnarFile::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::VarBufferedColumnarFile< BufferSize >::SetStride(), and casacore::SimpleColumnarFile::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_, and filename_.

Referenced by casacore::VarBufferedColumnarFile< BufferSize >::Write(), casacore::SimpleColumnarFile::Write(), casacore::VarBufferedColumnarFile< BufferSize >::WriteActiveBlock(), WriteHeader(), casacore::SimpleColumnarFile::WriteImplementation(), WritePrivateHeader(), and casacore::VarBufferedColumnarFile< BufferSize >::~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 ( )

inlineprivate

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 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(), 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(), 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(), Seek(), Truncate(), and WriteData().

◆ kFileVersion

constexpr uint32_t casacore::RowBasedFile::kFileVersion

inlinestaticconstexprprivate

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

constexpr uint32_t casacore::RowBasedFile::kMagicFileTag

inlinestaticconstexprprivate

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

constexpr uint32_t casacore::RowBasedFile::kWriterPrivateHeaderSize

inlinestaticconstexprprivate

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(), 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(), Truncate(), and casacore::UvwFile::UvwFile().

◆ 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(), SetStride(), Stride(), Truncate(), and WritePrivateHeader().

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

tables/AlternateMans/RowBasedFile.h

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RowBasedFile() [1/5]

◆ RowBasedFile() [2/5]

◆ RowBasedFile() [3/5]

◆ RowBasedFile() [4/5]

◆ RowBasedFile() [5/5]

◆ ~RowBasedFile()

Member Function Documentation

◆ AddRows()

◆ Close()

◆ CloseWithoutTruncate()

◆ DataLocation()

◆ DeleteRow()

◆ ErrorString()

◆ ErrorStringHelper() [1/2]

◆ ErrorStringHelper() [2/2]

◆ Filename()

◆ HeaderSize()

◆ IsOpen()

◆ NRows()

◆ operator=()

◆ ReadData()

◆ ReadHeader()

◆ Seek()

◆ SetNRows()

◆ SetStride()

◆ Stride()

◆ Truncate()

◆ WriteData()

◆ WriteHeader()

◆ WritePrivateHeader()

Member Data Documentation

◆ data_location_

◆ file_

◆ filename_

◆ kFileVersion

◆ kMagicFileTag

◆ kWriterPrivateHeaderSize

◆ n_rows_

◆ need_truncate_

◆ private_header_size_

◆ stride_