casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::MemoryIO Class Reference

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

#include <MemoryIO.h>

Inheritance diagram for casacore::MemoryIO:
casacore::ByteIO

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 uChargetBuffer () 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...
 
uCharsetBuffer (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)
 
MemoryIOoperator= (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

uCharitsBuffer
 
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...
 
ByteIOoperator= (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

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:

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: