Class for IO to a memory buffer. More...

#include <MemoryIO.h>

Inheritance diagram for casacore::MemoryIO:

Public Member Functions
	MemoryIO (uInt64 initialSize=65536, uInt64 expandSize=32768)
	Construct a dynamic object with the given initial length. More...

	MemoryIO (const void *buffer, uInt64 size)
	Construct from a buffer with the given length. More...

	MemoryIO (void *buffer, uInt64 size, ByteIO::OpenOption, uInt64 expandSize=0, Bool canDelete=False)
	Construct from the given buffer with the given length. More...

	~MemoryIO ()
	Delete the Memory object. More...

virtual void	write (Int64 size, const void *buf)
	Write the number of bytes. More...

virtual Int64	read (Int64 size, void *buf, Bool throwException=True)
	Read `size` bytes from the memory buffer. More...

void	clear ()
	Clear the buffer; i.e. More...

const uChar *	getBuffer () const
	Get the buffer containing the data. More...

virtual Int64	length ()
	Get the length of the data in the buffer. More...

uInt64	allocated () const
	Get the allocated length of the buffer. More...

uInt64	expandSize () const
	Get the expand size (0 = not expandable). More...

virtual Bool	isReadable () const
	Is the IO stream readable? More...

virtual Bool	isWritable () const
	Is the IO stream writable? More...

virtual Bool	isSeekable () const
	Is the IO stream seekable? More...

uChar *	setBuffer (uInt64 length)
	resize the internal buffer (if necessary) so that it is big enough to hold the specified number of bytes. More...

void	setUsed (uInt64 bytesUsed)
	tell the MemoryIO object how much of its internal buffer is valid data. More...

Public Member Functions inherited from casacore::ByteIO
	ByteIO ()
	The constructor does nothing. More...

virtual	~ByteIO ()

virtual void	pwrite (Int64 size, Int64 offset, const void *buf)
	Write `size` bytes to the byte stream at `offset`. More...

virtual Int64	pread (Int64 size, Int64 offset, void *buf, Bool throwException=True)
	Like read but reads from offset of start of the file The file offset is not changed. More...

virtual void	reopenRW ()
	Reopen the underlying IO stream for read/write access. More...

Int64	seek (Int offset, ByteIO::SeekOption=ByteIO::Begin)
	This function sets the position on the given offset. More...

Int64	seek (Int64 offset, ByteIO::SeekOption=ByteIO::Begin)

virtual void	flush ()
	Flush the data to the file. More...

virtual void	fsync ()
	Fsync the file (i.e. More...

virtual void	resync ()
	Resync the file (i.e. More...

virtual String	fileName () const
	Get the file name of the file attached. More...

Private Member Functions
	MemoryIO (const MemoryIO &that)

MemoryIO &	operator= (const MemoryIO &that)

virtual Int64	doSeek (Int64 offset, ByteIO::SeekOption)
	Reset the position pointer to the given value. More...

Bool	expand (uInt64 minSize)

Private Attributes
uChar *	itsBuffer

Int64	itsAlloc

Int64	itsExpandSize

Int64	itsUsed

Int64	itsPosition

Bool	itsReadable

Bool	itsWritable

Bool	itsCanDelete

Additional Inherited Members
Public Types inherited from casacore::ByteIO
enum	OpenOption { Old, Update, Append, New, NewNoReplace, Scratch, Delete }
	Define the possible ByteIO open options. More...

enum	SeekOption { Begin, Current, End }
	Define the possible seek options. More...

Protected Member Functions inherited from casacore::ByteIO
	ByteIO (const ByteIO &byteIO)
	Make copy constructor and assignment protected, so a user cannot use them (but a derived class can). More...

ByteIO &	operator= (const ByteIO &byteIO)

Detailed Description

Class for IO to a memory buffer.

Intended use:

Public interface

Review Status

Reviewed By:: Friso Olnon
Date Reviewed:: 1996/11/06
Test programs:: tByteIO

Prerequisite

ByteIO

Synopsis

This class is doing IO in a buffer in memory. It is part of the entire IO framework. It can for instance be used to store data in canonical format in a memory string and obtain it later.

The memory buffer can be dynamic, so it will be expanded when needed. This is done by allocating a larger buffer, copy the contents and throw the old buffer away.
The memory buffer can also be static to be sure that the pointer to the buffer will not change. The expand size determines if the memory buffer is static or dynamic. An expand size zero indicates a static buffer.

The memory buffer is seekable and readable. It depends on the constructor whether it is writable.

There are several ways in which the buffer can be created/passed:

Dynamic by passing an initial size and an expand size. However, an expand size zero can be used to assure that no more data is written than fits in the initial buffer (so once the buffer is created it gets static). In this way the buffer is readable and writable.
Static by passing a const buffer and its length. In this way the buffer is not writable.
Dynamic or static by passing a non-const buffer, its length, and an expand size (zero = static, >0 = dynamic) . The OpenOption indicates whether the buffer will be writable. Only for ByteIO::Old it will not be writable. The OpenOption also determines the initial seek position. Usually it is 0, but for ByteIO::Append it is the end of the buffer.

The user can obtain a pointer to the buffer to extract the stored data from it. The length of the data can also be obtained.

Usually this class will be used in combination with, say, CanonicalIO and AipsIO.

Example

// Create dynamic (expandable) memory buffer of length 100.
// Use that as the sink of RawIO in AipsIO.
MemoryIO membuf (100);
RawIO rawio (&membuf);
AipsIO stream (&rawio);
// Write values.
stream << (Int)10;
stream << True;
// Seek to beginning of buffer and read data in.
stream.setpos (0);
Int vali;
Bool valb;
stream >> vali >> valb;
// One can obtain the buffer and its length and use it later.
// (e.g. to write it in a non-AipsIO file).
uChar* bufptr = membuf.getBuffer();
uInt64 length = membuf.length();
// It can also used to construct another MemoryIO object from it.
// The following memory buffer is static and readonly.
MemoryIO membuf2 (bufptr, length);
membuf2.read (sizeof(vali), vali);
membuf2.read (sizeof(valb), valb);

Motivation

Make it possible to do IO in a memory buffer. The first implementation used strstreambuf from the iostream package. However, that did not allow seeking and it was hard to get the length.

Definition at line 124 of file MemoryIO.h.

Constructor & Destructor Documentation

casacore::MemoryIO::MemoryIO	(	uInt64	initialSize = `65536`,
		uInt64	expandSize = `32768`
	)

explicit

Construct a dynamic object with the given initial length.

casacore::MemoryIO::MemoryIO	(	const void *	buffer,
		uInt64	size
	)

Construct from a buffer with the given length.

The buffer is readonly and cannot be expanded.

casacore::MemoryIO::MemoryIO	(	void *	buffer,
		uInt64	size,
		ByteIO::OpenOption	,
		uInt64	expandSize = `0`,
		Bool	canDelete = `False`
	)

Construct from the given buffer with the given length.

The Byte::Option determines how the buffer will be used. The seek pointer is set to the beginning of the buffer, unless told otherwise below.

New, NewNoReplace and Scratch: The buffer is empty and is read/write.
Old: The buffer contains size bytes and is readonly.
Update, Delete: The buffer contains size bytes and is read/write.
Append: The buffer contains size bytes and is read/write. The seek pointer is set to the end of the buffer.

When the buffer is writable, it will be expanded if needed. This means that buffer does not point to the data anymore. However, when expandSize==0, the buffer cannot be expanded and the pointer is always valid.
When canDelete is True, buffer expansion means that the old buffer gets deleted.

casacore::MemoryIO::~MemoryIO ( )

Delete the Memory object.

The data buffer is not deleted when constructed with the constructor taking a buffer pointer.

casacore::MemoryIO::MemoryIO ( const MemoryIO & that )

private

Member Function Documentation

uInt64 casacore::MemoryIO::allocated ( ) const

inline

Get the allocated length of the buffer.

Definition at line 263 of file MemoryIO.h.

References itsAlloc.

void casacore::MemoryIO::clear ( )

inline

Clear the buffer; i.e.

set the data length and seek pointer to zero.

Definition at line 255 of file MemoryIO.h.

References itsPosition, and itsUsed.

virtual Int64 casacore::MemoryIO::doSeek	(	Int64	offset,
		ByteIO::SeekOption
	)

privatevirtual

Reset the position pointer to the given value.

It returns the new position. An exception is thrown when seeking before the start of the buffer or when seeking past the end of a readonly buffer. When seeking past the end of a writable buffer, the required amount of bytes is added and initialized to zero.

Implements casacore::ByteIO.

Bool casacore::MemoryIO::expand ( uInt64 minSize )

private

uInt64 casacore::MemoryIO::expandSize ( ) const

inline

Get the expand size (0 = not expandable).

Definition at line 267 of file MemoryIO.h.

References itsExpandSize.

const uChar * casacore::MemoryIO::getBuffer ( ) const

inline

Get the buffer containing the data.

The length of the data in the buffer can be obtained using the length() function.

Definition at line 259 of file MemoryIO.h.

References itsBuffer.

virtual Bool casacore::MemoryIO::isReadable ( ) const

virtual

Is the IO stream readable?

Implements casacore::ByteIO.

virtual Bool casacore::MemoryIO::isSeekable ( ) const

virtual

Is the IO stream seekable?

Implements casacore::ByteIO.

virtual Bool casacore::MemoryIO::isWritable ( ) const

virtual

Is the IO stream writable?

Implements casacore::ByteIO.

virtual Int64 casacore::MemoryIO::length ( )

virtual

Get the length of the data in the buffer.

Implements casacore::ByteIO.

MemoryIO& casacore::MemoryIO::operator= ( const MemoryIO & that )

private

virtual Int64 casacore::MemoryIO::read	(	Int64	size,
		void *	buf,
		Bool	throwException = `True`
	)

virtual

Read size bytes from the memory buffer.

Returns the number of bytes actually read. Will throw an Exception (AipsError) if the requested number of bytes could not be read unless throwException is set to False. Will always throw an exception if the buffer is not readable or the buffer pointer is at an invalid position.

Implements casacore::ByteIO.

uChar* casacore::MemoryIO::setBuffer ( uInt64 length )

resize the internal buffer (if necessary) so that it is big enough to hold the specified number of bytes.

Returns a non-const pointer to the buffer that can be used to write up to the specified number of bytes into the buffer. If less data is written into the buffer then the setUsed member funtion should be used to indicate how much of the buffer is valid. Throws an exception if the MemoryIO object is not writable or if it needs to increase the size of the internal buffer and the MemoryIO object is not expandable.
Warning: You should not use the supplied pointer to write more than length data points to the buffer

void casacore::MemoryIO::setUsed ( uInt64 bytesUsed )

tell the MemoryIO object how much of its internal buffer is valid data.

You only need to use this function if you are directly writing to the buffer using the pointer returned by the non-const getBuffer function. This function throws an exception if the number of bytes used is greater than the number allocated or if the MemoryIO object is not writeable.

virtual void casacore::MemoryIO::write	(	Int64	size,
		const void *	buf
	)

virtual

Write the number of bytes.

When needed it expands the buffer. An exception is thrown when the buffer is not writable or when buffer expansion fails or is not possible.

Implements casacore::ByteIO.

Member Data Documentation

Int64 casacore::MemoryIO::itsAlloc

private

Definition at line 245 of file MemoryIO.h.

Referenced by allocated().

uChar* casacore::MemoryIO::itsBuffer

private

Definition at line 244 of file MemoryIO.h.

Referenced by getBuffer().

Bool casacore::MemoryIO::itsCanDelete

private

Definition at line 251 of file MemoryIO.h.

Int64 casacore::MemoryIO::itsExpandSize

private

Definition at line 246 of file MemoryIO.h.

Referenced by expandSize().

Int64 casacore::MemoryIO::itsPosition

private

Definition at line 248 of file MemoryIO.h.

Referenced by clear().

Bool casacore::MemoryIO::itsReadable

private

Definition at line 249 of file MemoryIO.h.

Int64 casacore::MemoryIO::itsUsed

private

Definition at line 247 of file MemoryIO.h.

Referenced by clear().

Bool casacore::MemoryIO::itsWritable

private

Definition at line 250 of file MemoryIO.h.

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

casa/IO/MemoryIO.h

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Intended use:

Review Status

Prerequisite

Synopsis

Example

Motivation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation