evio
6.0
|
This is a class of interest to the user. More...
#include <EvioReaderV4.h>
Public Types | |
enum | ReadWriteStatus { SUCCESS = 0, END_OF_FILE, CANNOT_OPEN_FILE, EVIO_EXCEPTION, UNKNOWN_ERROR } |
This enum denotes the status of a read/write. More... | |
Public Member Functions | |||||||
EvioReaderV4 (std::string const &path, bool checkBlkNumSeq=false, bool synced=false) | |||||||
Constructor for reading an event file. More... | |||||||
EvioReaderV4 (std::shared_ptr< ByteBuffer > &byteBuffer, bool checkBlkNumSeq=false, bool synced=false) | |||||||
Constructor for reading a buffer. More... | |||||||
void | setBuffer (std::shared_ptr< ByteBuffer > &buf) override | ||||||
This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer.The method close() is called before anything else.
| |||||||
bool | isClosed () override | ||||||
Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))?
| |||||||
bool | checkBlockNumberSequence () override | ||||||
Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1?
| |||||||
ByteOrder & | getByteOrder () override | ||||||
Get the byte order of the file/buffer being read.
| |||||||
uint32_t | getEvioVersion () override | ||||||
Get the evio version number.
| |||||||
std::string | getPath () override | ||||||
Get the path to the file.
| |||||||
std::shared_ptr< EventParser > & | getParser () override | ||||||
Get the file/buffer parser.
| |||||||
void | setParser (std::shared_ptr< EventParser > &evParser) override | ||||||
Set the file/buffer parser.
| |||||||
std::string | getDictionaryXML () override | ||||||
Get the XML format dictionary if there is one.
| |||||||
bool | hasDictionaryXML () override | ||||||
Does this evio file have an associated XML dictionary?
| |||||||
std::shared_ptr< EvioEvent > | getFirstEvent () override | ||||||
Get the "first" event if there is one.It's also called the Beginning-Of-Run event. This event is defined once but included in each of the related split files written out.
| |||||||
bool | hasFirstEvent () override | ||||||
Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.This event is defined once but included in each of the related split files written out.
| |||||||
size_t | getNumEventsRemaining () override | ||||||
Get the number of events remaining in the file.Useful only if doing a sequential read.
| |||||||
std::shared_ptr< ByteBuffer > | getByteBuffer () override | ||||||
Get the byte buffer being read.Not useful when reading files.
| |||||||
size_t | fileSize () override | ||||||
Get the size of the file being read, in bytes.
| |||||||
std::shared_ptr< IBlockHeader > | getFirstBlockHeader () override | ||||||
This returns the FIRST block (record) header.
| |||||||
std::shared_ptr< EvioEvent > | getEvent (size_t index) override | ||||||
Get the event in the file/buffer at a given index (starting at 1).As useful as this sounds, most applications will probably call parseNextEvent() or parseEvent(size_t) instead, since it combines combines getting an event with parsing it.
| |||||||
std::shared_ptr< EvioEvent > | parseEvent (size_t index) override | ||||||
This is a workhorse method.It retrieves the desired event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.
| |||||||
std::shared_ptr< EvioEvent > | nextEvent () override | ||||||
Get the next event in the file/buffer.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines getting the next event with parsing the next event.Although this method can get events in versions 4+, it now delegates that to another method. No changes were made to this method from versions 1-3 in order to read the version 4 format as it is subset of versions 1-3 with variable block length.
| |||||||
std::shared_ptr< EvioEvent > | parseNextEvent () override | ||||||
This is a workhorse method.It retrieves the next event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.
| |||||||
void | parseEvent (std::shared_ptr< EvioEvent > evioEvent) override | ||||||
This will parse an event, SAX-like.It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines combines getting the next event with parsing the next event.This method is only called by synchronized methods and therefore is not synchronized.
| |||||||
uint32_t | getEventArray (size_t evNumber, std::vector< uint8_t > &vec) override | ||||||
Get an evio bank or event in vector-of-bytes form.
| |||||||
uint32_t | getEventBuffer (size_t evNumber, ByteBuffer &buf) override | ||||||
Get an evio bank or event in ByteBuffer form.
| |||||||
void | rewind () override | ||||||
The equivalent of rewinding the file.What it actually does is set the position of the file/buffer back to where it was after calling the constructor - after the first header.
| |||||||
ssize_t | position () override | ||||||
This is equivalent to obtaining the current position in the file.What it actually does is return the position of the buffer. Only meaningful to evio versions 1-3 and for sequential reading.
| |||||||
void | close () override | ||||||
This is closes the file, but for buffers it only sets the position to 0. More... | |||||||
std::shared_ptr< IBlockHeader > | getCurrentBlockHeader () override | ||||||
This returns the current (active) block (physical record) header.Since most users have no interest in physical records, this method should not be used.
| |||||||
std::shared_ptr< EvioEvent > | gotoEventNumber (size_t evNumber) override | ||||||
Go to a specific event in the file.The events are numbered 1..N. This number is transient–it is not part of the event as stored in the evio file. In versions 4 and up this is just a wrapper on getEvent(size_t).
| |||||||
size_t | getEventCount () override | ||||||
This is the number of events in the file/buffer.Any dictionary or first event are not included in the count.
| |||||||
size_t | getBlockCount () override | ||||||
This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end.
| |||||||
Static Public Attributes | |
static const uint32_t | MAGIC_OFFSET = 28 |
Offset to get magic number from start of file. More... | |
static const uint32_t | VERSION_OFFSET = 20 |
Offset to get version number from start of file. More... | |
static const uint32_t | BLOCK_SIZE_OFFSET = 0 |
Offset to get block size from start of block. More... | |
static const uint32_t | VERSION_MASK = 0xff |
Mask to get version number from 6th int in block. More... | |
static const uint32_t | DEFAULT_READ_BYTES = 32768 * 500 |
Default size for a single file read in bytes when reading evio format 1-3. More... | |
Protected Member Functions | |
void | parseFirstHeader (std::shared_ptr< ByteBuffer > &headerBuf) |
Reads 8 words of the first block (physical record) header in order to determine the evio version # and endianness of the file or buffer in question. More... | |
IEvioReader::ReadWriteStatus | processNextBlock () |
Reads the block (physical record) header. More... | |
This is a class of interest to the user.
It is used to read any evio version format file or buffer. Create an EvioReader
object corresponding to an event file or file-formatted buffer, and from this class you can test it for consistency and, more importantly, you can call parseNextEvent or parseEvent(size_t) to get new events and to stream the embedded structures to an IEvioListener.
A word to the wise, constructors for reading a file in random access mode (by setting "sequential" arg to false), will memory map the file. This is not a good idea if the file is not on a local disk.
The streaming effect of parsing an event is that the parser will read the event and hand off structures, such as banks, to any IEvioListeners. For those familiar with XML, the event is processed SAX-like. It is up to the listener to decide what to do with the structures.
As an alternative to stream processing, after an event is parsed, the user can use the events' tree structure for access its nodes. For those familiar with XML, the event is processed DOM-like.
|
inherited |
This enum
denotes the status of a read/write.
Used internally.
SUCCESS indicates a successful read.
END_OF_FILE indicates that we cannot read because an END_OF_FILE has occurred. Technically this means that whatever we are trying to read is larger than the buffer's unread bytes.
CANNOT_OPEN_FILE indicates that we cannot write because the destination file cannot be opened.
EVIO_EXCEPTION indicates that an EvioException was thrown during a read/write, possibly due to out of range values.
UNKNOWN_ERROR indicates that an unrecoverable error has occurred.
Enumerator | |
---|---|
SUCCESS | |
END_OF_FILE | |
CANNOT_OPEN_FILE | |
EVIO_EXCEPTION | |
UNKNOWN_ERROR |
|
explicit |
Constructor for reading an event file.
Do not set sequential to false for remote files.
path | the full path to the file that contains events. For writing event files, use an EventWriter object. |
checkBlkNumSeq | if true check the block number sequence and throw an exception if it is not sequential starting with 1 |
synced | if true, this class's methods are mutex protected for thread safety. |
EvioException | if file arg is null; if read failure; if first block number != 1 when checkBlkNumSeq arg is true |
References parseFirstHeader(), and parseNextEvent().
|
explicit |
Constructor for reading a buffer.
bb | the buffer that contains events. |
checkBlkNumSeq | if true check the block number sequence and throw an exception if it is not sequential starting with 1 |
synced | if true, this class's methods are mutex protected for thread safety. |
EvioException | if buffer arg is null; if first block number != 1 when checkBlkNumSeq arg is true |
References parseFirstHeader().
|
overridevirtual |
Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1?
true
if checking block number sequence, else false
Implements evio::IEvioReader.
|
overridevirtual |
This is closes the file, but for buffers it only sets the position to 0.
Implements evio::IEvioReader.
Referenced by setBuffer().
|
overridevirtual |
Get the size of the file being read, in bytes.
Implements evio::IEvioReader.
|
overridevirtual |
This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end.
EvioException | if object closed. |
Implements evio::IEvioReader.
|
overridevirtual |
Get the byte buffer being read.Not useful when reading files.
For files, it works only for evio format versions 2,3 and returns the internal buffer containing an evio block if using sequential access (for example files > 2.1 GB). It returns the memory mapped buffer otherwise.
Implements evio::IEvioReader.
|
overridevirtual |
Get the byte order of the file/buffer being read.
Implements evio::IEvioReader.
|
overridevirtual |
This returns the current (active) block (physical record) header.Since most users have no interest in physical records, this method should not be used.
Implements evio::IEvioReader.
|
overridevirtual |
Get the XML format dictionary if there is one.
Implements evio::IEvioReader.
|
overridevirtual |
Get the event in the file/buffer at a given index (starting at 1).As useful as this sounds, most applications will probably call parseNextEvent() or parseEvent(size_t) instead, since it combines combines getting an event with parsing it.
index | number of event desired, starting at 1, from beginning of file/buffer |
EvioException | if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed |
Implements evio::IEvioReader.
Referenced by getFirstEvent(), nextEvent(), and parseEvent().
|
overridevirtual |
Get an evio bank or event in vector-of-bytes form.
evNumber | number of event of interest (starting at 1). |
vec | vector to contain bank's/event's bytes. |
EvioException | if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed |
Implements evio::IEvioReader.
|
overridevirtual |
Get an evio bank or event in ByteBuffer form.
evNumber | number of event of interest |
buf | buffer to contain bank's/event's bytes. |
EvioException | if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed |
Implements evio::IEvioReader.
References evio::ByteBuffer::array(), evio::ByteBuffer::expand(), and evio::ByteBuffer::limit().
|
overridevirtual |
This is the number of events in the file/buffer.Any dictionary or first event are not included in the count.
EvioException | if read failure; if failed file access; if object closed |
Implements evio::IEvioReader.
References hasDictionaryXML(), nextEvent(), and rewind().
Referenced by getNumEventsRemaining().
|
overridevirtual |
|
overridevirtual |
This returns the FIRST block (record) header.
Implements evio::IEvioReader.
|
overridevirtual |
Get the "first" event if there is one.It's also called the Beginning-Of-Run event. This event is defined once but included in each of the related split files written out.
Implements evio::IEvioReader.
References getEvent(), and hasFirstEvent().
|
overridevirtual |
Get the number of events remaining in the file.Useful only if doing a sequential read.
EvioException | if failed reading from file |
Implements evio::IEvioReader.
References getEventCount().
|
overridevirtual |
|
overridevirtual |
|
overridevirtual |
Go to a specific event in the file.The events are numbered 1..N. This number is transient–it is not part of the event as stored in the evio file. In versions 4 and up this is just a wrapper on getEvent(size_t).
evNumber | the event number in a 1..N counting sense, from the start of the file. |
EvioException | if object closed; if failed file access |
Implements evio::IEvioReader.
|
overridevirtual |
Does this evio file have an associated XML dictionary?
true
if this evio file has an associated XML dictionary, else false
Implements evio::IEvioReader.
Referenced by getEventCount(), and rewind().
|
overridevirtual |
Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.This event is defined once but included in each of the related split files written out.
true
if this evio file has an associated first event, else false
Implements evio::IEvioReader.
Referenced by getFirstEvent().
|
overridevirtual |
Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))?
Implements evio::IEvioReader.
|
overridevirtual |
Get the next event in the file/buffer.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines getting the next event with parsing the next event.Although this method can get events in versions 4+, it now delegates that to another method. No changes were made to this method from versions 1-3 in order to read the version 4 format as it is subset of versions 1-3 with variable block length.
null
. EvioException | if failed file access; if failed read due to bad buffer format; if object closed |
Implements evio::IEvioReader.
References getEvent(), evio::EvioEvent::getInstance(), and processNextBlock().
Referenced by getEventCount(), parseNextEvent(), and rewind().
|
overridevirtual |
This is a workhorse method.It retrieves the desired event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.
index | number of event desired, starting at 1, from beginning of file/buffer |
EvioException | if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed |
Implements evio::IEvioReader.
References getEvent().
Referenced by parseNextEvent().
|
overridevirtual |
This will parse an event, SAX-like.It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines combines getting the next event with parsing the next event.This method is only called by synchronized methods and therefore is not synchronized.
evioEvent | the event to parse. |
EvioException | if bad format |
Implements evio::IEvioReader.
|
protected |
Reads 8 words of the first block (physical record) header in order to determine the evio version # and endianness of the file or buffer in question.
These things do not need to be examined in subsequent block headers. Called only by synchronized methods or constructors.
headerBuf | buffer containing data to parse. |
EvioException | if buffer too small, contains invalid data, or bad block # sequence |
References evio::ByteOrder::getOppositeEndian(), evio::BlockHeaderV4::HEADER_SIZE, evio::IBlockHeader::MAGIC_NUMBER, MAGIC_OFFSET, VERSION_MASK, and VERSION_OFFSET.
Referenced by EvioReaderV4(), and setBuffer().
|
overridevirtual |
This is a workhorse method.It retrieves the next event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.
null
. EvioException | if failed file access; if read failure or bad format; if object closed |
Implements evio::IEvioReader.
References nextEvent(), and parseEvent().
Referenced by EvioReaderV4().
|
overridevirtual |
This is equivalent to obtaining the current position in the file.What it actually does is return the position of the buffer. Only meaningful to evio versions 1-3 and for sequential reading.
EvioException | if object closed; if error accessing file |
Implements evio::IEvioReader.
|
protected |
Reads the block (physical record) header.
Assumes mapped buffer or file is positioned at start of the next block header. If a sequential file: version 4, Read the entire next block into internal buffer. version 1-3, If unused data still exists in internal buffer, don't read anymore in right now as there is at least 1 block there (integral # of blocks read in). If no data in internal buffer read DEFAULT_READ_BYTES or the rest of the file, whichever is smaller, into the internal buffer.
By the time this is called, the version # and byte order have already been determined. Not necessary to do that for each block header that's read. Called from synchronized method.
A Bank header is 8, 32-bit ints. The first int is the size of the block in ints (not counting the length itself, i.e., the number of ints to follow).
Most users should have no need for this method, since most applications do not care about the block (physical record) header.
EvioException | if file access problems, evio format problems |
References DEFAULT_READ_BYTES, evio::BlockHeaderV4::HEADER_SIZE, and SWAP_32.
Referenced by nextEvent().
|
overridevirtual |
The equivalent of rewinding the file.What it actually does is set the position of the file/buffer back to where it was after calling the constructor - after the first header.
EvioException | if object closed; if failed file access or buffer/file read |
Implements evio::IEvioReader.
References hasDictionaryXML(), and nextEvent().
Referenced by getEventCount().
|
overridevirtual |
This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer.The method close() is called before anything else.
buf | ByteBuffer to be read. |
underflow_error | if not enough data in buffer. |
EvioException | if buf is null; buf not in proper format; if first record/block number != 1 when checkRecNumSeq arg is true. |
Implements evio::IEvioReader.
References close(), and parseFirstHeader().
|
overridevirtual |
|
static |
Offset to get block size from start of block.
|
static |
Default size for a single file read in bytes when reading evio format 1-3.
Equivalent to 500, 32,768 byte blocks. This constant MUST BE an integer multiple of 32768.
Referenced by processNextBlock().
|
static |
Offset to get magic number from start of file.
Referenced by parseFirstHeader().
|
static |
Mask to get version number from 6th int in block.
Referenced by parseFirstHeader().
|
static |
Offset to get version number from start of file.
Referenced by parseFirstHeader().