CompressedVectorWriter Class Reference

An iterator object keeping track of a write in progress to a CompressedVectorNode. More...

List of all members.

Public Member Functions
void	write (const size_t requestedRecordCount)
	Request transfer of blocks of data to CompressedVectorNode from previously designated source buffers.
void	write (std::vector< SourceDestBuffer > &sbufs, const size_t requestedRecordCount)
	Request transfer of block of data to CompressedVectorNode from given source buffers.
void	close ()
	End the write operation.
bool	isOpen ()
	Test whether CompressedVectorWriter is still open for writing.
CompressedVectorNode	compressedVectorNode () const
	Return the CompressedVectorNode being written to.
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 CompressedVectorWriter class invariant is true.

---

Detailed Description

An iterator object keeping track of a write in progress to a CompressedVectorNode.

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

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

There is no CompressedVectorWriter constructor in the API. The function CompressedVectorNode::writer returns an already constructed CompressedVectorWriter object with given memory buffers (SourceDestBuffers) already associated. CompressedVectorWriter::close must explicitly be called to safely and gracefully end the transfer.

Warning: If CompressedVectorWriter::close is not called before the CompressedVectorWriter destructor is invoked, all writes to the CompressedVectorNode will be lost (it will have zero children).

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 CompressedVectorWriter::checkInvariant(bool /*doRecurse*/) {
    // If this CompressedVectorWriter 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 be writable
    if (!imf.isWritable())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // Dest ImageFile must have exactly 1 writer (this one)
    if (imf.writerCount() != 1)
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

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

See also:

CompressedVectorNode, CompressedVectorReader