Class to write Evio-6.0/HIPO files. More...

#include <Writer.h>

Public Member Functions
	Writer ()
	Default constructor. More...

	Writer (const ByteOrder &order, uint32_t maxEventCount=0, uint32_t maxBufferSize=0)
	Constructor with byte order. More...

	Writer (const std::string &filename, const ByteOrder &order, uint32_t maxEventCount=0, uint32_t maxBufferSize=0)
	Constructor with filename & byte order. More...

	Writer (const HeaderType &hType, const ByteOrder &order=ByteOrder::ENDIAN_LOCAL, uint32_t maxEventCount=0, uint32_t maxBufferSize=0, const std::string &dictionary=std::string(""), uint8_t *firstEvent=nullptr, uint32_t firstEventLength=0, const Compressor::CompressionType &compressionType=Compressor::UNCOMPRESSED, bool addTrailerIndex=false)
	Constructor with byte order. More...

	Writer (std::shared_ptr< ByteBuffer > &buf)
	Constructor for writing to a ByteBuffer. More...

	Writer (std::shared_ptr< ByteBuffer > &buf, uint8_t *userHdr, uint32_t len)
	Constructor with user header. More...

	Writer (std::shared_ptr< ByteBuffer > &buf, uint32_t maxEventCount, uint32_t maxBufferSize, const std::string &dictionary, uint8_t *firstEvent, uint32_t firstEventLength)
	Constructor with byte order. More...

	~Writer ()=default

const ByteOrder &	getByteOrder () const
	Get the file's byte order. More...

std::shared_ptr< ByteBuffer >	getBuffer ()
	Get the buffer being written to. More...

FileHeader &	getFileHeader ()
	Get the file header. More...

Compressor::CompressionType	getCompressionType ()
	Get the internal record's header. More...

void	setCompressionType (Compressor::CompressionType compression)
	Convenience method that sets compression type for the file. More...

bool	addTrailer () const
	Does this writer add a trailer to the end of the file/buffer? More...

void	addTrailer (bool add)
	Set whether this writer adds a trailer to the end of the file/buffer. More...

bool	addTrailerWithIndex ()
	Does this writer add a trailer with a record index to the end of the file? Or, if writing to a buffer, is a trailer added with no index? More...

void	addTrailerWithIndex (bool addTrailingIndex)
	Set whether this writer adds a trailer with a record index to the end of the file. More...

void	open (const std::string &filename)
	Open a new file and write file header with no user header. More...

void	open (const std::string &filename, uint8_t *userHdr, uint32_t len)
	Open a file and write file header with given user header. More...

void	open (std::shared_ptr< ByteBuffer > &buf, uint8_t *userHdr, uint32_t len)
	Specify a buffer and write first record header with given user header. More...

std::shared_ptr< ByteBuffer >	createHeader (uint8_t *userHdr, uint32_t userLen)
	Create and return a buffer containing a general file header followed by the user header given in the argument. More...

std::shared_ptr< ByteBuffer >	createHeader (ByteBuffer &userHdr)
	Create and return a buffer containing a general file header followed by the user header given in the argument. More...

void	createHeader (ByteBuffer &buf, uint8_t *userHdr, uint32_t userLen)
	Fill given buffer with a general file header followed by the given user header. More...

void	createHeader (ByteBuffer &buf, ByteBuffer &userHdr)
	Fill given buffer (buf) with a general file header followed by the given user header (userHdr). More...

void	writeRecord (RecordOutput &record)
	Appends the record to the file/buffer. More...

void	addEvent (uint8_t *buffer, uint32_t length)
	Add a byte array to the internal record. More...

void	addEvent (std::shared_ptr< ByteBuffer > &buffer)
	Add a ByteBuffer to the internal record. More...

void	addEvent (ByteBuffer &buffer)
	Add a ByteBuffer to the internal record. More...

void	addEvent (std::shared_ptr< EvioBank > &bank)
	Add an EvioBank to the internal record. More...

void	addEvent (std::shared_ptr< EvioNode > &node)
	Add an EvioNode to the internal record. More...

void	addEvent (EvioNode &node)
	Add an EvioNode to the internal record. More...

void	reset ()
	Get this object ready for re-use. More...

void	close ()
	Close opened file. More...

Static Public Member Functions
static std::shared_ptr < ByteBuffer >	createRecord (const std::string &dictionary, uint8_t firstEvent, uint32_t firstEventLen, const ByteOrder &byteOrder, FileHeader fileHeader, RecordHeader *recordHeader)
	STATIC. More...

Detailed Description

Class to write Evio-6.0/HIPO files.

Version: 6.0

Since: 6.0 8/10/17

Author: timmer

Constructor & Destructor Documentation

evio::Writer::Writer ( )

Default constructor.

No file is opened. Any file will have little endian byte order.

evio::Writer::Writer	(	const ByteOrder &	order,
		uint32_t	maxEventCount = `0`,
		uint32_t	maxBufferSize = `0`
	)

explicit

Constructor with byte order.

No file is opened. File header type is evio file (HeaderType#EVIO_FILE).

Parameters

order	byte order of written file.
maxEventCount	max number of events a record can hold. Value of O means use default (1M).
maxBufferSize	max number of uncompressed data bytes a record can hold. Value of < 8MB results in default of 8MB.

evio::Writer::Writer	(	const std::string &	filename,
		const ByteOrder &	order,
		uint32_t	maxEventCount = `0`,
		uint32_t	maxBufferSize = `0`
	)

Constructor with filename & byte order.

The output file will be created with no user header. No compression.

Parameters

filename	output file name
order	byte order of written file;
maxEventCount	max number of events a record can hold. Value of O means use default (1M).
maxBufferSize	max number of uncompressed data bytes a record can hold. Value of < 8MB results in default of 8MB.

Exceptions

EvioException if file cannot be found or IO error writing to file

References open().

evio::Writer::Writer	(	const HeaderType &	hType,
		const ByteOrder &	order = `ByteOrder::ENDIAN_LOCAL`,
		uint32_t	maxEventCount = `0`,
		uint32_t	maxBufferSize = `0`,
		const std::string &	dictionary = `std::string("")`,
		uint8_t *	firstEvent = `nullptr`,
		uint32_t	firstEventLen = `0`,
		const Compressor::CompressionType &	compType = `Compressor::UNCOMPRESSED`,
		bool	addTrailerIndex = `false`
	)

explicit

Constructor with byte order.

The given file is opened so any subsequent call to open will fail. This method places the dictionary and first event into the file header's user header.

Parameters

hType	the type of the file. If set to HeaderType#HIPO_FILE, the header will be written with the first 4 bytes set to HIPO.
order	byte order of written file.
maxEventCount	max number of events a record can hold. Value of O means use default (1M).
maxBufferSize	max number of uncompressed data bytes a record can hold. Value of < 8MB results in default of 8MB.
dictionary	string holding an evio format dictionary to be placed in userHeader.
firstEvent	byte array containing an evio event to be included in userHeader. It must be in the same byte order as the order argument.
firstEventLen	number of bytes in firstEvent.
compType	type of data compression to do (one, lz4 fast, lz4 best, gzip)
addTrailerIndex	if true, we add a record index to the trailer.

References evio::RecordHeader::HEADER_SIZE_BYTES, and evio::HeaderType::HIPO_FILE.

evio::Writer::Writer ( std::shared_ptr< ByteBuffer > & buf )

explicit

Constructor for writing to a ByteBuffer.

Byte order is taken from the buffer. No compression.

Parameters

buf	buffer in to which to write events and/or records.

evio::Writer::Writer	(	std::shared_ptr< ByteBuffer > &	buf,
		uint8_t *	userHdr,
		uint32_t	len
	)

Constructor with user header.

No compression.

Parameters

buf	buffer in to which to write events and/or records.
userHdr	byte array representing the optional user's header. Warning: this will not be used until first record is written! So don't go changing it in the meantime!
len	length of valid data (bytes) in userHdr (starting at off).

References open().

evio::Writer::Writer	(	std::shared_ptr< ByteBuffer > &	buf,
		uint32_t	maxEventCount,
		uint32_t	maxBufferSize,
		const std::string &	dictionary,
		uint8_t *	firstEvent,
		uint32_t	firstEventLen
	)

Constructor with byte order.

This method places the dictionary and first event into the file header's user header. No compression.

Parameters

buf	buffer in to which to write events and/or records.
maxEventCount	max number of events a record can hold. Value of O means use default (1M).
maxBufferSize	max number of uncompressed data bytes a record can hold. Value of < 8MB results in default of 8MB.
dictionary	string holding an evio format dictionary to be placed in userHeader.
firstEvent	byte array containing an evio event to be included in userHeader. It must be in the same byte order as the order argument.
firstEventLen	number of bytes in firstEvent.

References evio::RecordHeader::HEADER_SIZE_BYTES, and evio::Compressor::UNCOMPRESSED.

evio::Writer::~Writer ( )

default

Member Function Documentation

void evio::Writer::addEvent	(	uint8_t *	buf,
		uint32_t	length
	)

Add a byte array to the internal record.

If the length of the buffer exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe. The byte order of event's byte array must match the byte order given in constructor!

Parameters

buf	buffer to add to the file.
length	number of bytes to write from buffer.

Exceptions

EvioException if cannot write to file.

Referenced by addEvent().

void evio::Writer::addEvent ( std::shared_ptr< ByteBuffer > & buf )

Add a ByteBuffer to the internal record.

If the length of the buffer exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe. The byte order of event's data must match the byte order given in constructor!

Parameters

buf	buffer to add to the file.

Exceptions

EvioException if cannot write to file or buf arg's byte order is wrong.

References addEvent().

void evio::Writer::addEvent ( ByteBuffer & buf )

Add a ByteBuffer to the internal record.

If the length of the buffer exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe. The byte order of event's data must match the byte order given in constructor!

Parameters

buf	buffer to add to the file.

Exceptions

EvioException if cannot write to file or buf arg's byte order is wrong.

References evio::ByteBuffer::order().

void evio::Writer::addEvent ( std::shared_ptr< EvioBank > & bank )

Add an EvioBank to the internal record.

If the length of the bank exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe.

Parameters

bank	event to add to the file.

Exceptions

IOException if cannot write to file.

void evio::Writer::addEvent ( std::shared_ptr< EvioNode > & node )

Add an EvioNode to the internal record.

If the length of the data exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe. The byte order of node's data must match the byte order given in constructor!

Parameters

node	node to add to the file.

Exceptions

EvioException	if node does not correspond to a bank.
IOException	if cannot write to file.

References addEvent().

void evio::Writer::addEvent ( EvioNode & node )

Add an EvioNode to the internal record.

If the length of the data exceeds the maximum size of the record, the record will be written to the file (compressed if the flag is set). Internal record will be reset to receive new buffers. Using this method in conjunction with writeRecord() is not thread-safe. The byte order of node's data must match the byte order given in constructor!

Parameters

node	node to add to the file.

Exceptions

EvioException	if node does not correspond to a bank.
IOException	if cannot write to file.

bool evio::Writer::addTrailer ( ) const

Does this writer add a trailer to the end of the file/buffer?

Returns: true if this writer adds a trailer to the end of the file/buffer, else false.

void evio::Writer::addTrailer ( bool add )

Set whether this writer adds a trailer to the end of the file/buffer.

Parameters

add	if true, at the end of file/buffer, add an ending header (trailer) with no index of records and no following data. Update the file header to contain a file offset to the trailer.

bool evio::Writer::addTrailerWithIndex ( )

Does this writer add a trailer with a record index to the end of the file? Or, if writing to a buffer, is a trailer added with no index?

Returns: if writing to a file: true if this writer adds a trailer with a record index to the end of the file, else false. If writing to a buffer, true if this writer adds a traile to the end of the buffer, else false.

void evio::Writer::addTrailerWithIndex ( bool addTrailingIndex )

Set whether this writer adds a trailer with a record index to the end of the file.

Or, if writing to a buffer, set whether a trailer is added with no index.

Parameters

addTrailingIndex if true, at the end of file, add an ending header (trailer) with an index of all records but with no following data. Update the file header to contain a file offset to the trailer. If true, and writing to a buffer, add a trailer with no index to the end of the buffer.

void evio::Writer::close ( )

Close opened file.

If the output record contains events, they will be flushed to file/buffer. Trailer and its optional index written if requested.

Exceptions

IOException if error writing to file

References evio::RecordHeader::BIT_INFO_OFFSET, evio::ByteOrder::ENDIAN_LOCAL, evio::FileHeader::hasTrailerWithIndex(), evio::FileHeader::RECORD_COUNT_OFFSET, SWAP_32, SWAP_64, and evio::FileHeader::TRAILER_POSITION_OFFSET.

std::shared_ptr< ByteBuffer > evio::Writer::createHeader	(	uint8_t *	userHdr,
		uint32_t	userLen
	)

Create and return a buffer containing a general file header followed by the user header given in the argument.

If user header is not padded to 4-byte boundary, it's done here.

Parameters

userHdr	byte array containing a user-defined header, may be null.
userLen	array length in bytes.

Returns: buffer (same as buf arg).

Exceptions

EvioException if writing to buffer, not file.

References evio::FileHeader::getLength(), evio::FileHeader::HEADER_SIZE_BYTES, evio::FileHeader::reset(), evio::FileHeader::setBitInfo(), evio::FileHeader::setUserHeaderLength(), and evio::FileHeader::writeHeader().

Referenced by open().

std::shared_ptr< ByteBuffer > evio::Writer::createHeader ( ByteBuffer & userHdr )

Create and return a buffer containing a general file header followed by the user header given in the argument.

If user header is not padded to 4-byte boundary, it's done here.

Parameters

userHdr buffer containing a user-defined header which must be READY-TO-READ!

Returns: buffer containing a file header followed by the user-defined header.

Exceptions

EvioException if writing to buffer, not file.

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::FileHeader::getLength(), evio::FileHeader::HEADER_SIZE_BYTES, evio::ByteBuffer::position(), evio::ByteBuffer::remaining(), evio::FileHeader::reset(), evio::FileHeader::setBitInfo(), evio::FileHeader::setUserHeaderLength(), and evio::FileHeader::writeHeader().

void evio::Writer::createHeader	(	ByteBuffer &	buf,
		uint8_t *	userHdr,
		uint32_t	userLen
	)

Fill given buffer with a general file header followed by the given user header.

The buffer is cleared and set to desired byte order prior to writing. If user header is not padded to 4-byte boundary, it's done here.

Parameters

buf	buffer to contain the file header followed by the user-defined header.
userHdr	byte array containing a user-defined header, may be null.
userLen	array length in bytes.

Exceptions

EvioException if writing to buffer, or buf too small (needs to be userLen + FileHeader::HEADER_SIZE_BYTES bytes).

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::ByteBuffer::capacity(), evio::ByteBuffer::clear(), evio::FileHeader::getLength(), evio::FileHeader::HEADER_SIZE_BYTES, evio::ByteBuffer::limit(), evio::ByteBuffer::order(), evio::FileHeader::reset(), evio::FileHeader::setBitInfo(), evio::FileHeader::setUserHeaderLength(), and evio::FileHeader::writeHeader().

void evio::Writer::createHeader	(	ByteBuffer &	buf,
		ByteBuffer &	userHdr
	)

Fill given buffer (buf) with a general file header followed by the given user header (userHdr).

The buffer is cleared and set to desired byte order prior to writing. If user header is not padded to 4-byte boundary, it's done here.

Parameters

buf	buffer to contain the file header followed by the user-defined header.
userHdr	buffer containing a user-defined header which must be READY-TO-READ!

Exceptions

EvioException if writing to buffer, or buf too small (needs to be userHdr.remaining() + FileHeader::HEADER_SIZE_BYTES bytes).

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::ByteBuffer::capacity(), evio::ByteBuffer::clear(), evio::FileHeader::getLength(), evio::FileHeader::HEADER_SIZE_BYTES, evio::ByteBuffer::limit(), evio::ByteBuffer::order(), evio::ByteBuffer::position(), evio::ByteBuffer::remaining(), evio::FileHeader::reset(), evio::FileHeader::setBitInfo(), evio::FileHeader::setUserHeaderLength(), and evio::FileHeader::writeHeader().

std::shared_ptr< ByteBuffer > evio::Writer::createRecord	(	const std::string &	dict,
		uint8_t *	firstEv,
		uint32_t	firstEvLen,
		const ByteOrder &	order,
		FileHeader *	fileHdr,
		RecordHeader *	recordHdr
	)

static

STATIC.

Create a buffer representation of a record containing dictionary and/or first event. No compression.

Parameters

dict	dictionary xml string
firstEv	bytes representing evio event
firstEvLen	number of bytes in firstEv
order	byte order of returned byte array
fileHdr	file header to update with dictionary/first-event info (may be null).
recordHdr	record header to update with dictionary info (may be null).

Returns: buffer representation of record containing dictionary and/or first event. Null pointer if both are empty/null.

References evio::RecordOutput::addEvent(), evio::RecordOutput::build(), evio::RecordOutput::getBinaryBuffer(), evio::RecordOutput::getInternalBufferCapacity(), evio::FileHeader::hasDictionary(), evio::RecordHeader::hasDictionary(), evio::FileHeader::hasFirstEvent(), and evio::Compressor::UNCOMPRESSED.

std::shared_ptr< ByteBuffer > evio::Writer::getBuffer ( )

Get the buffer being written to.

This should only be called after calling close() so data is complete.

Returns: buffer being written to.

const ByteOrder & evio::Writer::getByteOrder ( ) const

Get the file's byte order.

Returns: file's byte order.

Compressor::CompressionType evio::Writer::getCompressionType ( )

Get the internal record's header.

Returns: internal record's header. Get the internal record used to add events to file.; internal record used to add events to file. Convenience method that gets compression type for the file being written.; compression type for the file being written.

FileHeader & evio::Writer::getFileHeader ( )

Get the file header.

Returns: file header.

void evio::Writer::open ( const std::string & filename )

Open a new file and write file header with no user header.

Parameters

filename output file name

Exceptions

EvioException	if open already called without being followed by calling close.
IOException	if file cannot be found or IO error writing to file

Referenced by Writer().

void evio::Writer::open	(	const std::string &	filename,
		uint8_t *	userHdr,
		uint32_t	userLen
	)

Open a file and write file header with given user header.

User header is automatically padded when written.

Parameters

filename	name of file to write to.
userHdr	byte array representing the optional user's header. If this is null AND dictionary and/or first event are given, the dictionary and/or first event will be placed in its own record and written as the user header.
userLen	length of valid data (bytes) in userHdr (starting at off).

Exceptions

EvioException filename arg is null, if constructor specified writing to a buffer, if open() was already called without being followed by reset(), if file cannot be found, if IO error writing to file, or if filename is empty.

References createHeader(), and evio::FileHeader::getLength().

void evio::Writer::open	(	std::shared_ptr< ByteBuffer > &	buf,
		uint8_t *	userHdr,
		uint32_t	len
	)

Specify a buffer and write first record header with given user header.

User header is automatically padded when written.

Parameters

buf	buffer to writer to.
userHdr	byte array representing the optional user's header. Warning: this data will be copied! If this is null AND dictionary and/or first event are given, the dictionary and/or first event will be placed in its own record and written as the user header of the first record's header.
len	length of valid data (bytes) in userHdr.

Exceptions

EvioException if constructor specified writing to a file, or if open() was already called without being followed by reset().

void evio::Writer::reset ( )

Get this object ready for re-use.

Follow calling this with call to open(const std::string &).

References evio::FileHeader::reset().

void evio::Writer::setCompressionType ( Compressor::CompressionType compression )

Convenience method that sets compression type for the file.

The compression type is also set for internal record. When writing to the file, record data will be compressed according to the given type.

Parameters

compression compression type

void evio::Writer::writeRecord ( RecordOutput & rec )

Appends the record to the file/buffer.

When writing to a file, using this method in conjunction with addEvent() is NOT thread-safe. For that reason, this write is done synchronously, to avoid interference with the normal, asynchronous file writes. Thus, writing using this method will not be quite as efficient.

Parameters

rec	record object

Exceptions

EvioException if error writing to file or record's byte order is opposite to output endian.

References evio::RecordOutput::build(), evio::RecordOutput::getBinaryBuffer(), evio::RecordOutput::getByteOrder(), and evio::RecordOutput::getHeader().

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation