CompressedVectorReader Class Reference

An iterator object keeping track of a read in progress from a CompressedVectorNode. More...

List of all members.

Public Member Functions
unsigned	read ()
	Request transfer of blocks of data from CompressedVectorNode into previously designated destination buffers.
unsigned	read (std::vector< SourceDestBuffer > &dbufs)
	Request transfer of block of data from CompressedVectorNode into given destination buffers.
void	seek (int64_t recordNumber)
	Set record number of CompressedVectorNode where next read will start.
void	close ()
	End the read operation.
bool	isOpen ()
	Test whether CompressedVectorReader is still open for reading.
CompressedVectorNode	compressedVectorNode () const
	Return the CompressedVectorNode being read.
void	dump (int indent=0, std::ostream &os=std::cout) const
	Diagnostic function to print internal state of object to output stream in an indented format.
void	checkInvariant (bool doRecurse=true)
	Check whether CompressedVectorReader class invariant is true.

---

Detailed Description

An iterator object keeping track of a read in progress from a CompressedVectorNode.

A CompressedVectorReader object is a block iterator that reads blocks of records from a CompressedVectorNode and stores them in memory buffers (SourceDestBuffers). Blocks of records are processed rather than a single record-at-a-time for efficiency reasons. The CompressedVectorReader class encapsulates all the state that must be saved in between the processing of one record block and the next (e.g. partially read disk pages, or data decompression state). New memory buffers can be used for each record block read, or the previous buffers can be reused.

CompressedVectorReader objects have an open/closed state. Initially a newly created CompressedVectorReader is in the open state. After the API user calls CompressedVectorReader::close, the object will be in the closed state and no more data transfers will be possible.

There is no CompressedVectorReader constructor in the API. The function CompressedVectorNode::reader returns an already constructed CompressedVectorReader object with given memory buffers (SourceDestBuffers) already associated.

It is recommended to call CompressedVectorReader::close to gracefully end the transfer. Unlike the CompressedVectorWriter, not all fields in the record of the CompressedVectorNode are required to be read at one time.

Class Invariant

A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:

void CompressedVectorReader::checkInvariant(bool /*doRecurse*/) {
    // If this CompressedVectorReader is not open, can't test invariant (almost every call would throw)
    if (!isOpen())
        return;

    CompressedVectorNode cv = compressedVectorNode();
    ImageFile imf = cv.destImageFile();

    // If destImageFile not open, can't test invariant (almost every call would throw)
    if (!imf.isOpen())
        return;

    // Associated CompressedVectorNode must be attached to ImageFile
    if (!cv.isAttached())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // Dest ImageFile must have at least 1 reader (this one)
    if (imf.readerCount() < 1)
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // Dest ImageFile can't have any writers
    if (imf.writerCount() != 0)
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
} // end CompressedVectorReader::checkInvariant

See also:

CompressedVectorNode, CompressedVectorWriter