If two blocks of memory are written consecutively, when reading the data there is no easy way to determine where one block ends and the next one begins. If you want to write blocks of memory that are always read as atomic units, use chunk I/O.

When a block of memory is written using write_chunk() , the memory block is preceded by code that indicates the use of chunk format; then, the memory block is followed by the size of the block and the data. Streaming<ToolKit> builds this data structure in an internal buffer and writes the entire structure using a single system call. The write_chunk() function returns the number of user bytes successfully written, not including the overhead of the header. On most systems, the entire overhead for writing a chunk is 12 bytes.

When a block of memory is read using read_chunk() , Streaming<ToolKit> can determine the end of the block and reads the block as an atomic unit. There are two versions of read_chunk() : one that reads a chunk into the heap and one that reads the chunk into an existing segment of memory.

If you try to read a chunk into a segment of memory that is too small, an error is generated. The read_chunk() function returns the number of user bytes successfully read, not including the overhead of the header.

The following example uses chunk I/O to save and restore two structures. The first structure is read into the heap, whereas the second structure is read into a block of memory.

Example <ospace/stream/examples/chunkio1.cpp>


  #include <fstream>
#include <ospace/stream.h>

struct my_struct
  {
  int a;
  double d;
  };

void
display( char* str, my_struct* data, int bytes )
  {
  cout << str << bytes << " bytes: " << data->a << ", ";
  cout << data->d << endl;
  }

void
write()
  {
  fstream file( "chunkio1.bin", ios::binary | ios::out | ios::trunc );
  os_bstream stream( os_adapter_for( file ) );
  my_struct struct1;
  struct1.a = 42;
  struct1.d = 3.14;
  my_struct struct2;
  struct2.a = 1;
  struct2.d = 2.13;

  int bytes = stream.write_chunk( &struct1, sizeof( struct1 ) );
  display( "Write ", &struct1, bytes );
  stream.write_chunk( &struct2, sizeof( struct2 ) );
  display( "Write ", &struct2, bytes );
  }

void
read()
  {
  fstream file( "chunkio1.bin", ios::binary | ios::in );
  os_bstream stream( os_adapter_for( file ) );

  my_struct* struct1; // Will point to chunk on heap.
  int bytes = stream.read_chunk( (void*&) struct1 );
  display( "Read ", struct1, bytes );
  delete struct1; // Deallocate memory.

  my_struct struct2;
  bytes = stream.read_chunk( &struct2, sizeof( struct2 ) );
  display( "Read ", &struct2, bytes );
  }

void
main()
  {
  os_streaming_toolkit initialize;
  write();
  read();
  }

Write 16 bytes: 42, 3.14
Write 16 bytes: 1, 2.13
Read 16 bytes: 42, 3.14
Read 16 bytes: 1, 2.13

Chunk I/O

Example <ospace/stream/examples/chunkio1.cpp>