evio  6.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Static Public Member Functions | List of all members
evio::RecordInput Class Reference

Class which reads data to create an Evio or HIPO Record. More...

#include <RecordInput.h>

Public Member Functions

 RecordInput ()
 Default constructor. More...
 
 RecordInput (const ByteOrder &order)
 Constructor. More...
 
 RecordInput (const RecordInput &recordIn)
 Copy constructor. More...
 
 RecordInput (RecordInput &&srcRec) noexcept
 Move constructor. More...
 
 ~RecordInput ()=default
 
RecordInput & operator= (RecordInput &&other) noexcept
 Move assignment operator. More...
 
RecordInput & operator= (const RecordInput &other)
 Assignment operator. More...
 
std::shared_ptr< RecordHeader > getHeader ()
 Get the header of this record. More...
 
const ByteOrder & getByteOrder ()
 Get the byte order of the internal buffers. More...
 
std::shared_ptr< ByteBuffer > getUncompressedDataBuffer ()
 Get the buffer with all uncompressed data in it. More...
 
bool hasIndex () const
 Does this record contain an event index? More...
 
bool hasUserHeader () const
 Does this record contain a user header? More...
 
std::shared_ptr< ByteBuffer > getEvent (std::shared_ptr< ByteBuffer > &buffer, uint32_t index, size_t bufOffset=0)
 Get the event at the given index and write it into the given byte buffer. More...
 
ByteBuffer & getEvent (ByteBuffer &buffer, uint32_t index, size_t bufOffset=0)
 Get the event at the given index and write it into the given byte buffer. More...
 
std::shared_ptr< uint8_t > getUserHeader ()
 Get the user header contained in this record and return it in an allocated array. More...
 
std::shared_ptr< ByteBuffer > getUserHeader (std::shared_ptr< ByteBuffer > &buffer, size_t bufOffset=0)
 Get any existing user header and write it into the given byte buffer. More...
 
ByteBuffer & getUserHeader (ByteBuffer &buffer, size_t bufOffset=0)
 Get any existing user header and write it into the given byte buffer. More...
 
std::shared_ptr< uint8_t > getEvent (uint32_t index, uint32_t *len)
 Get the event at the given index and return it in an allocated array. More...
 
uint32_t getEventLength (uint32_t index) const
 Returns the length of the event with given index. More...
 
uint32_t getEntries () const
 Returns number of the events packed in the record. More...
 
std::shared_ptr< RecordInput > getUserHeaderAsRecord (ByteBuffer &buffer, size_t bufOffset)
 Get any existing user header and write it into the given byte buffer. More...
 
void readRecord (std::ifstream &file, size_t position)
 Reads record from the file at given position. More...
 
void readRecord (ByteBuffer &buffer, size_t offset)
 Reads a record from the buffer at the given offset. More...
 

Static Public Member Functions

static uint32_t uncompressRecord (std::shared_ptr< ByteBuffer > &srcBuf, size_t srcOff, std::shared_ptr< ByteBuffer > &dstBuf, RecordHeader &hdr)
 Uncompress the data of a record from the source buffer at the given offset into the destination buffer. More...
 
static uint32_t uncompressRecord (ByteBuffer &srcBuf, size_t srcOff, ByteBuffer &dstBuf, RecordHeader &header)
 Uncompress the data of a record from the source buffer at the given offset into the destination buffer. More...
 

Detailed Description

Class which reads data to create an Evio or HIPO Record.

This class is NOT thread safe!


RECORD STRUCTURE:
              Uncompressed                                      Compressed
   +----------------------------------+            +----------------------------------+
   |       General Record Header      |            |       General Record Header      |
   +----------------------------------+            +----------------------------------+
   +----------------------------------+ ---------> +----------------------------------+
   |           Index Array            |            |        Compressed Data           |
   +----------------------------------+            |             Record               |
                                                   |                                  |
   +----------------------------------+            |                                  |
   |           User Header            |            |                  ----------------|
   |           (Optional)             |            |                  |    Pad 3      |
   |                  ----------------|            +----------------------------------+
   |                  |    Pad 1      |           ^
   +----------------------------------+          /
                                                /
   +----------------------------------+       /
   |           Data Record            |     /
   |                                  |    /
   |                  ----------------|   /
   |                  |    Pad 2      | /
   +----------------------------------+
GENERAL RECORD HEADER STRUCTURE ( see RecordHeader.java )
   +----------------------------------+
 1 |         Record Length            | // 32bit words, inclusive
   +----------------------------------+
 2 +         Record Number            |
   +----------------------------------+
 3 +         Header Length            | // 14 (words)
   +----------------------------------+
 4 +       Event (Index) Count        |
   +----------------------------------+
 5 +      Index Array Length          | // bytes
   +-----------------------+---------+
 6 +       Bit Info        | Version  | // version (8 bits)
   +-----------------------+----------+
 7 +      User Header Length          | // bytes
   +----------------------------------+
 8 +          Magic Number            | // 0xc0da0100
   +----------------------------------+
 9 +     Uncompressed Data Length     | // bytes
   +------+---------------------------+
10 +  CT  |  Data Length Compressed   | // CT = compression type (4 bits)
   +----------------------------------+
11 +        General Register 1        | // UID 1st (64 bits)
   +--                              --+
12 +                                  |
   +----------------------------------+
13 +        General Register 2        | // UID 2nd (64 bits)
   +--                              --+
14 +                                  |
   +----------------------------------+
Version
6.0
Since
6.0 10/13/17
Author
gavalian
timmer (C++ version)

Constructor & Destructor Documentation

evio::RecordInput::RecordInput ( )

Default constructor.

References evio::ByteBuffer::order().

evio::RecordInput::RecordInput ( const ByteOrder &  order)
explicit

Constructor.

Parameters
orderbyte order of internal byte arrays.
evio::RecordInput::RecordInput ( const RecordInput &  srcRec)

Copy constructor.

evio::RecordInput::RecordInput ( RecordInput &&  srcRec)
noexcept

Move constructor.

Parameters
srcRecRecordInput to move.
evio::RecordInput::~RecordInput ( )
default

Member Function Documentation

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

Get the byte order of the internal buffers.

Returns
byte order of the internal buffers.
uint32_t evio::RecordInput::getEntries ( ) const

Returns number of the events packed in the record.

Returns
number of the events packed in the record

Referenced by evio::Reader::getEvent(), getEventLength(), evio::Reader::getEventLength(), and evio::Reader::getRecordEventCount().

std::shared_ptr< ByteBuffer > evio::RecordInput::getEvent ( std::shared_ptr< ByteBuffer > &  buffer,
uint32_t  index,
size_t  bufOffset = 0 
)

Get the event at the given index and write it into the given byte buffer.

The given byte buffer has to be large enough to receive all the event's data, but the buffer->limit() is ignored & reset. Buffer's byte order is set to that of the internal buffers.

Parameters
bufferbuffer to be filled with event.
indexindex of event starting at 0.
bufOffsetoffset into buffer to place event.
Returns
buffer buffer arg.
Exceptions
EvioExceptionif index too large, or buffer has insufficient space to contain event (buffer->capacity() < event size).

Referenced by evio::Reader::extractDictionaryFromBuffer(), evio::Reader::extractDictionaryFromFile(), and evio::Reader::getEvent().

ByteBuffer & evio::RecordInput::getEvent ( ByteBuffer &  buffer,
uint32_t  index,
size_t  bufOffset = 0 
)

Get the event at the given index and write it into the given byte buffer.

The given byte buffer has to be large enough to receive all the event's data, but the buffer.limit() is ignored & reset. Buffer's byte order is set to that of the internal buffers.

Parameters
bufferbuffer to be filled with event.
indexindex of event starting at 0.
bufOffsetoffset into buffer to place event.
Returns
buffer buffer arg.
Exceptions
EvioExceptionif index too large, or buffer has insufficient space to contain event (buffer.capacity() < event size).

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::ByteBuffer::capacity(), evio::ByteBuffer::limit(), and evio::ByteBuffer::order().

std::shared_ptr< uint8_t > evio::RecordInput::getEvent ( uint32_t  index,
uint32_t *  len 
)

Get the event at the given index and return it in an allocated array.

Parameters
indexindex of event starting at 0. If index too large, it's set to last index.
lenpointer to int which gets filled with the data length in bytes.
Returns
byte array containing event.
uint32_t evio::RecordInput::getEventLength ( uint32_t  index) const

Returns the length of the event with given index.

Parameters
indexindex of the event
Returns
length of the data in bytes or zero if index does not coresspond to a valid event.

References getEntries().

Referenced by evio::Reader::getEventLength().

std::shared_ptr< RecordHeader > evio::RecordInput::getHeader ( )

Get the header of this record.

Returns
header of this record.
std::shared_ptr< ByteBuffer > evio::RecordInput::getUncompressedDataBuffer ( )

Get the buffer with all uncompressed data in it.

It's position and limit are set to read only event data. That means no header, index, or user-header.

Returns
the buffer with uncompressed event data in it.
std::shared_ptr< uint8_t > evio::RecordInput::getUserHeader ( )

Get the user header contained in this record and return it in an allocated array.

Returns
the user header contained in this record, or null if none.

Referenced by getUserHeader(), and getUserHeaderAsRecord().

std::shared_ptr< ByteBuffer > evio::RecordInput::getUserHeader ( std::shared_ptr< ByteBuffer > &  buffer,
size_t  bufOffset = 0 
)

Get any existing user header and write it into the given byte buffer.

The given byte buffer must be large enough to contain user header. Buffer's byte order is set to that of the internal buffers. Buffer's position is set to bufOffset and limit is set to bufOffset + userHeader size.

Parameters
bufferbuffer to be filled with user header.
bufOffsetoffset into buffer to place user header.
Returns
buffer passed in (position = limit = bufOffset if no user header exists).
Exceptions
EvioExceptionif buffer has insufficient space to contain user header (buffer.capacity() - bufOffset < user header size).

References getUserHeader().

ByteBuffer & evio::RecordInput::getUserHeader ( ByteBuffer &  buffer,
size_t  bufOffset = 0 
)

Get any existing user header and write it into the given byte buffer.

The given byte buffer must be large enough to contain user header. Buffer's byte order is set to that of the internal buffers. Buffer's position is set to bufOffset and limit is set to bufOffset + userHeader size.

Parameters
bufferbuffer to be filled with user header.
bufOffsetoffset into buffer to place user header.
Returns
buffer passed in (position = limit = bufOffset if no user header exists).
Exceptions
EvioExceptionif buffer has insufficient space to contain user header (buffer.capacity() - bufOffset < user header size).

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::ByteBuffer::capacity(), evio::ByteBuffer::limit(), and evio::ByteBuffer::order().

std::shared_ptr< RecordInput > evio::RecordInput::getUserHeaderAsRecord ( ByteBuffer &  buffer,
size_t  bufOffset 
)

Get any existing user header and write it into the given byte buffer.

The byte buffer must be large enough to contain it. Warning, buffer.limit() is ignored & reset. Parse the user header into the given recordInput object which will be set to the byte order of this object.

Parameters
bufferbuffer to be filled with user header
bufOffsetoffset into buffer to place user header.
Returns
record parsed from user header or nullptr if no user header exists.
Exceptions
EvioExceptionif buffer has insufficient space to contain user header (buffer.capacity() - bufOffset < user header size), or if buffer not in hipo format.

References getUserHeader(), and evio::ByteBuffer::remaining().

bool evio::RecordInput::hasIndex ( ) const

Does this record contain an event index?

Returns
true if record contains an event index, else false.
bool evio::RecordInput::hasUserHeader ( ) const

Does this record contain a user header?

Returns
true if record contains a user header, else false.
RecordInput & evio::RecordInput::operator= ( RecordInput &&  other)
noexcept

Move assignment operator.

Parameters
otherright side object.
Returns
left side object.
RecordInput & evio::RecordInput::operator= ( const RecordInput &  other)

Assignment operator.

Parameters
otherright side object.
Returns
left side object.
void evio::RecordInput::readRecord ( std::ifstream &  file,
size_t  position 
)

Reads record from the file at given position.

Call this method or readRecord(ByteBuffer &, size_t) before calling any other. Any compressed data is decompressed. Memory is allocated as needed. First the header is read, then the length of the record is read from header, then following bytes are read and decompressed.

Parameters
fileopened file descriptor
positionposition in the file
Exceptions
EvioExceptionif file contains too little data, if the input data was corrupted (including if the input data is an incomplete stream), is not in proper format, or version earlier than 6, or error in uncompressing gzipped data.

References evio::ByteBuffer::array(), evio::ByteBuffer::capacity(), evio::Compressor::getInstance(), evio::RecordHeader::HEADER_SIZE_BYTES, evio::ByteBuffer::order(), and evio::Compressor::uncompressLZ4().

Referenced by evio::Reader::extractDictionaryFromBuffer(), evio::Reader::extractDictionaryFromFile(), and evio::Reader::readRecord().

void evio::RecordInput::readRecord ( ByteBuffer &  buffer,
size_t  offset 
)

Reads a record from the buffer at the given offset.

Call this method or readRecord(std::ifstream &, size_t) before calling any other. Any compressed data is decompressed. Memory is allocated as needed.

Parameters
bufferbuffer containing record data.
offsetoffset into buffer to beginning of record data.
Exceptions
EvioExceptionif buffer contains too little data, is not in proper format, or version earlier than 6 or error in uncompressing gzipped data.

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::Compressor::getInstance(), evio::ByteBuffer::limit(), evio::ByteBuffer::order(), and evio::Compressor::uncompressLZ4().

uint32_t evio::RecordInput::uncompressRecord ( std::shared_ptr< ByteBuffer > &  srcBuf,
size_t  srcOff,
std::shared_ptr< ByteBuffer > &  dstBuf,
RecordHeader &  hdr 
)
static

Uncompress the data of a record from the source buffer at the given offset into the destination buffer.

Be aware that the position & limit of srcBuf may be changed. The limit of dstBuf may be changed. The position of dstBuf will be set to just after the user-header and just before the data.

Parameters
srcBufbuffer containing record data.
srcOffoffset into srcBuf to beginning of record data.
dstBufbuffer into which the record is uncompressed.
hdrRecordHeader to be used to read the record header in srcBuf.
Returns
the original record size in srcBuf (bytes).
Exceptions
EvioExceptionif srcBuf contains too little data, is not in proper format, or version earlier than 6.

Referenced by evio::Reader::scanBuffer().

uint32_t evio::RecordInput::uncompressRecord ( ByteBuffer &  srcBuf,
size_t  srcOff,
ByteBuffer &  dstBuf,
RecordHeader &  hdr 
)
static

Uncompress the data of a record from the source buffer at the given offset into the destination buffer.

Be aware that the position & limit of srcBuf may be changed. The limit of dstBuf may be changed. The position of dstBuf will be set to just after the user-header and just before the data.

Parameters
srcBufbuffer containing record data.
srcOffoffset into srcBuf to beginning of record data.
dstBufbuffer into which the record is uncompressed.
hdrRecordHeader to be used to read the record header in srcBuf.
Returns
the original record size in srcBuf (bytes).
Exceptions
EvioExceptionif srcBuf contains too little data, is not in proper format, or version earlier than 6.

References evio::ByteBuffer::array(), evio::ByteBuffer::arrayOffset(), evio::RecordHeader::BIT_INFO_OFFSET, evio::ByteBuffer::capacity(), evio::RecordHeader::COMPRESSION_TYPE_OFFSET, evio::RecordHeader::getBitInfoWord(), evio::RecordHeader::getCompressedDataLength(), evio::RecordHeader::getCompressionType(), evio::RecordHeader::getDataLengthWords(), evio::RecordHeader::getHeaderLength(), evio::RecordHeader::getIndexLength(), evio::Compressor::getInstance(), evio::RecordHeader::getLength(), evio::RecordHeader::getUncompressedRecordLength(), evio::RecordHeader::getUserHeaderLengthWords(), evio::ByteBuffer::limit(), evio::ByteBuffer::position(), evio::ByteBuffer::put(), evio::ByteBuffer::putInt(), evio::RecordHeader::readHeader(), evio::RecordHeader::RECORD_LENGTH_OFFSET, evio::RecordHeader::setCompressedDataLength(), evio::RecordHeader::setCompressionType(), evio::RecordHeader::setLength(), evio::Compressor::UNCOMPRESSED, and evio::Compressor::uncompressLZ4().

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