Provided by: libbobcat-dev_4.01.03-2ubuntu1_amd64 
NAME
FBB::SharedMemory - Shared Memory memory structure
SYNOPSIS
#include <bobcat/sharedmemory>
Linking option: -lbobcat
DESCRIPTION
The class FBB::SharedMemory implements a usable interface to a shared memory segment made
available by FBB::SharedSegment and monitored by FBB::SharedPos. It is the main building
block for FBB::SharedStreambuf, defining the `device’ to which FBB::SharedStreambuf
interfaces. All shared memory related I/O should be performed by FBB::SharedMemory
objects, which are true objects, not themselves residing in shared memory.
An FBB::SharedMemory object defines, connects to and manages access to shared memory,
encapsulating all raw shared memory operations. In addition to the class FBB::SharedMemory
the header file bobcat/sharedmemory also defines a struct SharedEnum__ defining enum
SizeUnit within the namespace FBB.
The requested amount of shared memory is always a lower bound to the maximum amount of
shared memory that eventually may become available. When defining a SharedMemory object
not all of its potentially available shared memory is immediately allocated. Shared memory
will be allocated by the SharedMemory object once needed (up to a calculated maximum).
As a fictitious example: assume 100 kB of memory is requested. The SharedMemory object
then maintains a table of, e.g., 10 entries, each entry controlling access to a shared
memory block of 10 kB. These 10 kB blocks aren’t immediately allocated, but become
available once the program reads from or writes to addresses located in these data blocks.
Newly allocated data blocks are initialized to 0-bytes.
Caveat: when constructing a shared memory segment make sure the segment’s ID is stored at
a retrievable location. This allows other processes to access the shared segment. The
shared segment ID is also required to delete a shared memory segment. If the shared
segment ID is lost, the memory occupied by the shared memory segment remains inaccessible
(although they can be retrieved and removed by additional means, like ipcs(1) and
ipcrm(1)). The member id returns the ID of the shared memory currently monitored by an
FBB::SharedMemory object.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
FBB::SharedEnum__
The struct SharedEnum__ is a wrapper struct around enum SizeUnit, which is available
through inheritance in several FBB::Shared* classes, and offers symbolic constants
defining standard memory sizes. The enum SizeUnit defines the following symbolic
constants:
o kB, representing 1024 (2**10) bytes of memory;
o MB, representing 1048576 (2**20) bytes of memory;
o GB, representing 1073741824 (2**30) bytes of memory
CONSTRUCTORS, DESTRUCTOR
o SharedMemory():
The default constructor defines an empty stub, which cannot immediately be used.
As the SharedMemory class supports move assignment, empty stubs can easily be
(re)configured at any time after their construction.
o SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600):
This constructor creates a shared memory segment having a capacity of at least
maxSize * sizeUnit bytes. The shared memory’s access rights are defined by the
access parameter, using the well-known (chmod(1)) octal values to define access
rights for the owner, the group and others. If construction succeeds the shared
memory is ready for use. If construction fails, an FBB::Exception is thrown.
o SharedMemory(int id):
This constructor connects to a shared memory segment having ID id. If construction
succeeds the shared memory is ready for use. If construction fails (e.g., no shared
memory segment having ID id exists), an FBB::Exception is thrown.
o ~SharedMemory():
The destructor detaches any attached shared memory segments from the
FBB::SharedMemory object. If the shared memory segment is currently locked by the
FBB::SharedMemory object, the lock is removed.
copy and move constructors are not available.
OVERLOADED OPERATORS
o std::ostream &operator<<(std::ostream &out, SharedMemory const &sharedMemory):
The overloaded insertion operator inserts information about the SharedMemory object
into the provide ostream object. The IDs of the shared segments, their sizes, the
maximum number of shared memory segments, the number of bytes that can be read from
the shared memory, and its actual storage capacity, etc., are displayed.
o SharedMemory &operator=(SharedMemory &&rhs):
The overloaded move assignment operator is available. It is used to (re)define the
shared memory segment an FBB::SharedMemory object is interfacing with.
The overloaded copy assignement operator is not available.
MEMBER FUNCTIONS
o size_t blockOffset() const:
The offset within the shared segment data block matching offset’s return value is
returned. 0 is returned if the SharedMemory object has not yet been connected to a
shared memory block.
o void clear():
First, the shared memory is locked. Next, all shared data segment are deleted, and
the shared memory’s own data are reset to indicate it is completely empty.
Following this the shared memory segment is unlocked again. Returning from clear
the shared memory The FBB::SharedMemory object is effectively re-initialized, with
offset and nReadable returning 0.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o size_t dataSegmentSize() const:
Returns the size (in bytes) of shared memory data block. 0 is returned if the
SharedMemory object has not yet been connected to a shared memory block.
o int get():
First the FBB::SharedMemory object calls lock to lock the shared memory segment.
Next the character at offset is retrieved and offset is incremented. Then unlock is
called, and the retrieved character is returned. If offset is at least equal to
nReadable, EOF is immediately returned.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int id() const:
The ID of the shared memory segment is returned. Following kill id returns -1,
indicating that the shared segment cannot be used anymore (note that operator= can
be used to re-initialize the FBB::SharedMemory object).
o SharedType *install(std::streamsize *offset, Params &&...params):
This member was implemented as a member template, using typename SharedType and
typename ...Params, allowing perfect forwarding of arguments to SharedType’s
constructor.
This member installs a SharedType object at SharedMemory’s at SharedMemory’s first
available offset: either at the current offset, or (if SharedType’s size is too big
to fit in the current data block at offset) at the first byte of the next
SharedSegment shared data block.
The actual offset where the SharedType object is installed is returned in *offset,
unless a nullptr is passed as install’s first argument.
A pointer to the installed SharedType is returned, with shmem.offset pointing just
beyond SharedType’s last byte.
The SharedType object is installed using placement new. E.g., the following example
illustrates how a SharedMutex(3bobcat) object can be installed at the first
possible location of SharedMemory shmem:
std::streamsize offset;
FBB::SharedMutex *mutexPtr = shmem.install<FBB::SharedMutex>(&offset);
If the installed object must be destroyed, its destructor must explicitly be
called. E.g., to destroy the Mutex pointed at by mutexPtr use
mutexPtr->~SharedMutex().
An FBB::Exception is thrown if shmem could not install the object in its shared
memory data blocks.
o void kill():
Without locking the shared memory all shared memory controlled by the SharedMemory
object is deleted. The SharedMemory object is unusable after returning from kill,
with its id member returns -1. Nothing happens if this member is called when the
SharedMemory object has not yet been connected to a shared memory block.
o std::streamsize maxOffset() const:
The maximum possible offset that can be used with the shared memory segment is
returned. The members offset and nReadable never exceed the value returned by
maxOffset. 0 is returned if the SharedMemory object has not yet been connected to a
shared memory block.
o std::streamsize nReadable() const:
The number of characters (bytes) that can be read from the beginning of the shared
memory is returned. 0 is returned if the SharedMemory object has not yet been
connected to a shared memory block.
o std::streamsize offset() const:
The offset within the shared memory segment (i.e., relative to the segment’s
ios::beg position) is returned. 0 is returned if the SharedMemory object has not
yet been connected to a shared memory block.
o char *ptr():
Returns 0 if offset() == maxOffset(). Otherwise it returns a pointer to the
character at index offset within the shared memory segment.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int put(int ch):
After locking the appropriate shared data segment, ch is written at position
offset, incrementing offset thereafter. If ch == EOF, EOF is immediately returned.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int read(Type *value):
This member was implemented as a member template. It calls the next member, casting
Type * to char *, and using sizeof(Type) as its second argument. The number of
bytes actually read is returned. This member returns -1 if initially offset was at
least equal to nReadable.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int read(char *data, std::streamsize len):
While locking the appropriate shared data segment(s) at most len bytes are read
from the shared memory, starting at offset. The bytes read from shared memory are
stored at data. The number of bytes actually read is returned. This member returns
-1 if initially offset was at least equal to nReadable.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int read(std::ios::off_type offset, Type *value, std::ios::seekdir origin =
std::ios::beg):
This member was implemented as a member template. After changing the SharedMemory’s
offset to offset (relative to origin), it calls the first read member, passing it
value. The number of bytes actually read is returned. This member returns -1 if
initially offset was at least equal to nReadable.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o void remove():
The shared memory is locked, after which all shared memory controlled by the
FBB::SharedMemory object is deleted. The FBB::SharedMemory object is unusable after
returning from remove.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o std::ios::pos_type seek(std::ios::off_type offset, std::ios::seekdir origin =
std::ios::beg):
Moves the offset position relative to way. The value -1 is returned when seeking
before offset 0 or beyond maxOffset, otherwise the offset relative to the begin
location of the shared memory (i.e, offset for origin == ios::beg) is returned. 0
is returned if the SharedMemory object has not yet been connected to a shared
memory block.
o std::streamsize showmanyc() const:
The number of characters that can be read from the current shared segment data
block is returned. This member interrogates the number of readable characters in
the shared memory segment. This number may change while this member is being
executed. In order to receive a stable return value, calling functions should have
obtained a lock on the shared memory segment before calling this member. 0 is
returned if the SharedMemory object has not yet been connected to a shared memory
block.
o void swap(SharedMemory &other):
The current and other FBB::SharedMemory objects are swapped.
o bool truncate(std::streamsize offset):
If offset is not exceeding the value returned by nReadable nReadable is changed to
offset and true is returned. Otherwise false is returned, and the value returned by
nReadable is not changed.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int write(Type const *value):
This member was implemented as a member template. It calls the next member, casting
Type const * to char const *, and using sizeof(Type) as its second argument. The
number of bytes actually written is returned. This member returns -1 if initially
offset was at least equal to maxOffset.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int write(char const *data, std::streamsize len):
The FBB::SharedMemory object calls lock to lock the shared memory, and writes at
most len bytes into the shared memory, starting at offset. Next, unlock is called.
The number of bytes actually written is returned. The member function returns -1 if
initially offset is equal to maxOffset.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
o int write(std::ios::off_type offset, Type const *value, std::ios::seekdir origin =
std::ios::beg):
This member was implemented as a member template. After changing the SharedMemory’s
offset to offset (relative to origin), it calls the first write member, passing it
value. The number of bytes actually written is returned. This member returns -1 if
initially offset was at least equal to maxOffset.
An FBB::Exception is thrown if the SharedMemory object has not yet been connected
to a shared memory block.
EXAMPLE
See the sharedstream(3bobcat) man page.
FILES
bobcat/sharedmemory - defines the class interface
SEE ALSO
bobcat(7), chmod(1), ipcs(1), ipcrm(1), isharedstream(3bobcat), osharedstream(3bobcat),
sharedblock(3bobcat), sharedcondition(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat),
sharedreadme(7bobcat), sharedsegment(3bobcat), sharedstream(3bobcat),
sharedstreambuf(3bobcat)
BUGS
None Reported.
DISTRIBUTION FILES
o bobcat_4.01.03-x.dsc: detached signature;
o bobcat_4.01.03-x.tar.gz: source archive;
o bobcat_4.01.03-x_i386.changes: change log;
o libbobcat1_4.01.03-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.01.03-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
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).