NAME¶

FBB::MemoryBuf - streambuf interfacing to memory segments

SYNOPSIS¶

#include <bobcat/memorybuf>
Linking option: -lbobcat

DESCRIPTION¶

MemoryBuf implements a specialization of the std::streambuf class, allowing stream classes (std::iostream, FBB::MemoryStream) to perform I/O operations on memory segmnts (cf. shmget(2)).

FBB::MemoryBuf povides the streambufs of FBB::MemoryStream objects using a FBB::MemoryBridge object interfacing to the shared memory blocks read/written by a FBB::MemoryBuf object.

NAMESPACE¶

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM¶

std::streambuf.

CONSTRUCTORS¶

o

MemoryBuf():
The default constructor defines a stub MemoryBuf object that cannot immediately be used to access memory segments. In practice usable FBB::MemoryBuf objects are constructed by one of the following constructors.

o

MemoryBuf(std::string const &bufSize, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600):
Constructs a MemoryBuf object. Its default capacity is specified by bufSize (cf. section BUFSIZE), using memory segment(s) containing the stream’s bytes.

The access rights of the data stored in MemoryStream objects are defined by the access parameter, interpreted as an octal value, using the specifications used by (chmod(1)).

The erase parameter is used to specify what happens to the memory segments once the MemoryBuf object goes out of scope. When omitted or specified as false the allocated memory segments are not erased from memory when the object goes out of scope (and can be reaccessed until the computer is rebooted) using the memory object’s ID (see the next constructor). When specified as true the memory segments are erased from memory when the object goes out of scope.

If construction fails, an FBB::Exception is thrown.

o

MemoryBuf(int id, [bool erase,] std::ios::openmode openMode = std::ios::in | std::ios::out):
This constructor connects to a memory segment having ID id.

The erase parameter is used as it is used by the previous constructor.

Specifying the ios::trunc flag (or a comparable flag, like merely ios::out) immediately clears the current content of the memory segments.

An FBB::Exception is thrown if construction fails (e.g., no memory segment having ID id exists),

The move constructor and the move assignment operator are available, the copy constructor and copy assignment operator are not available.

BUFSIZE¶

The bufSize parameter required by the second MemoryStream constructor and the open member (see below) specifies the default number nummber of shared memory memory blocks and their sizes. The size of the memory blocks is specified as k, M or G, indicating block sizes in kilo-, Mega- and GigaBytes. Before those letters the default number of blocks is specified. E.g., "100M". Internally the number of kiloBytes is converted to `pages’, using the system’s page size, which is commonly equal to 4 kB (so when specifying "5k" then the stream prepares for two shared data segments, each having a capacity of 4 kB. The number of MegaBytes is used as specified, and when specifying GB the data segments are .5 GB.

The number of shared data segments is aotomatically enlarged when the current capacity is exceeded, and the potentially available data segments are initially not allocated: they’re allocated once information is written into their areas.

MEMBER FUNCTIONS¶

All members of std::streambuf are available.

o

int id() const:
The ID of the memory segments is returned.

o

void info(std::ostream &out):
Information about the MemoryBridge is inserted into out: the IDs of the memory data blocks, their sizes, the current maximum number of memory data blocks, the number of bytes that can be read from the memory segments, and its actual storage capacity.

o

std::streamsize maxEnd() const:
When using a MemoryBuf object the offset just beyond thecurrent maximum offset is returned. E.g., if a MemoryBuf object is configured with 5 data blocks of 1 MB each, then maxEnd returns 5 * 1024 * 1024. When the object extends its number of data blocks maxEnd returns the corresponding new value.

o

void setErase(bool erase):
This member is used to change the erase setting of a MemoryBuf object. It can be used by, e.g., forking programs where the program constructs a MemoryBuf object specifying erase == false, but whose memory segments should be erased when the parent process ends but not also when the child process ends. This is accomplished by calling setErase(true) in the parent process.

o

void truncate(std::streamsize size):
This member can be used to reduce or enlarge the available memory size of a MemoryBuf object to size. If it’s reduced then the memory segements’ data bytes from size to its original size are set to 0: newly allocated memory segments are always initialized to 0 byte values.

o

std::streamsize writtenUntil() const:
Returns the highest ever byte-offset where a value was written.

EXAMPLE¶

See the memorystream(3bobcat) man page.

FILES¶

bobcat/memorybuf - defines the class interface

SEE ALSO¶

bobcat(7), chmod(1), memorybridge(3bobcat), memoryreadme(7bobcat), memorystream(3bobcat), shmget(2),

BUGS¶

Note that by default exceptions thrown from within a std::stream object are caught by the stream object, setting its ios::failbit flag. To allow exceptions to leave a stream object, its exceptions member can be called, e.g., using:

    myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);


        

BOBCAT PROJECT FILES¶

o

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

Debian Bobcat project files:

o

libbobcat6: debian package containing the shared library, changelog and copyright note;

o

libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

BOBCAT¶

Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT¶

This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR¶

Frank B. Brokken (f.b.brokken@rug.nl).