FBB::SharedSegment - Shared Memory data structure
#include <bobcat/sharedsegment>
Linking option: -lbobcat
The class FBB::SharedSegment implements the shared memory
data structure used by Bobcat’s shared memory classes.
Bobcat’s SharedMemory class accesses or defines a shared
memory segment, controlling all its read and write operations.
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 SharedSegment object not all of its potentially
available shared memory is immediately allocated. Shared memory will be
allocated by the SharedSegment object once needed (up to a calculated
maximum).
As a fictitious example: assume 100 kB of memory is requested,
then the SharedSegment object, maintains a table of, e.g., 10
entries, each controlling the 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
segments.
The class SharedSegment therefore defines a gateway,
controlling access to and allocating required shared memory data segments.
The mentioned table consists of nBlocks SharedBlock
(sharedblock(3bobcat)) values, offering mutexes and IDs of shared
data segments. The mutexes control which process has access to a particular
block of shared data memory, and the IDs are either -1, meaning that their
shared memory data segments has as not yet been allocated, or they contain
the IDs of defined shared memory data segments.
The class SharedSegment’s sole responsibility is to
offer the framework as described. When used by a FBB::SharedMemory
object different processes may gain access to different parts of the shared
memory data without interfering each other’s read and write
actions.
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
No publicly accessible constructors have been defined for
SharedSegment. A static member function create (see below) is
available, returning a pointer to a shared memory segment, in which a
SharedSegment has been defined.
- o
- std::ostream &operator<<(std::ostream &out,
SharedSegment const &sharedData):
The overloaded insertion operator inserts basic statistics of the shared
memory data into the ostream object. Information about the IDs of
the shared segments, their sizes, the maximum number of shared data
segments and the number of bytes that can be read from the shared memory
are displayed.
- o
- FBB::SharedBlock &operator[](size_t idx):
Table element idx of the table of FBB::SharedBlock block IDs
is returned. The behavior of the program is undefined if idx is or
exceeds nBlocks().
- Copy and move constructors (and assignment operators) are not
available.
- o
- size_t access() const:
Returns the access rights of the shared memory segment as a number which is
usually interpreted as an octal value, using the well-known
(chmod(1)) way to define the access rights for owner, group and
others.
- o
- void clear():
All the shared memory data blocks are unconditionally deleted and
nReadable returns 0 (the shared memory data blocks are not locked
prior to deleting them). After calling clear all allocated
SharedSegment’s shared memory segments have ceased to exist
and can no longer be used.
- o
- void lock(size_t idx) const:
Access to shared data segment idx is locked. This member itself does
not support recursive locking.
- o
- size_t nBlocks() const:
Returns the number of shared memory data blocks that can be used by the
FBB::SharedSegment object.
- o
- int newData(size_t idx):
Returns the ID of a newly created shared memory data segment. The ID is also
stored in the table of shared memory data segments that is maintained by
the SharedSegment object.
- An FBB::Exception is thrown if the shared memory data segment could
not be allocated.
- o
- std::streamsize nReadable() const:
Returns the number of characters (bytes) that can be read from the beginning
of the shared memory.
- o
- void nReadableLock() const:
When returning from this member function a lock has been obtained of
SharedSegment’s mutex controlling access the the
object’s data member storing the number of characters that can be
read from the shared memory controlled by the SharedSegment
object.
- o
- void nReadableUnlock() const:
This member function releases the lock previously acquired by
nReadableLock.
- o
- size_t segmentSize() const:
Returns the size (in bytes) of the shared memory data blocks. The
SharedSegment object can accommodate at most segmentSize() *
nBlocks() bytes.
- o
- bool truncate(std::streamsize offset):
After calling nReadableLock, 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 has not been changed.
Before returning nReadableUnlock is called.
- o
- void unlock(size_t idx) const:
Releases the lock on the shared memory data segment idx. If the
current process does not own the lock of shared memory data block
idx nothing happens and the function immediately returns.
- o
- void updateNreadable(std::streamsize offset):
The number of bytes that can be retrieved from the shared memory is updated
to max(nReadable(), offset).
- o
- void *attach(int id):
Returns the address of shared memory segment id, mapped to the
calling process’s memory area.
- An FBB::Exception is thrown if the shared memory data segment could
not be attached.
- o
- SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize,
size_t access):
Returns a pointer to a newly created SharedSegment object, defined in
the computer’s shared memory.
- The created shared memory’s ID is stored at *id. The
remaining arguments define the potential number of shared memory data
blocks (nBlocks); the size of these data blocks
(segmentSize); and the shared memory’s access rights
(access, using the well-known octal value representation as used by
(chmod(1)) to define access rights for the owner, the group and
others).
- An FBB::Exception is thrown if the shared memory data segment could
not be created.
- o
- void deleteSegment(int id):
The shared memory segment having ID id is deleted. After calling
deleteSegment shared memory segment id doesn’t exist
anymore. The id can be the shared memory ID of any segment for
which the current user has write permissions.
- An FBB::Exception is thrown if shared memory data segment id
could not be deleted.
- o
- Type *detach(Type *sharedPtr, bool requireOK = true):
This member is defined as a member template. It expects a pointer to a
shared memory segment, previously mapped on the calling process’s
memory space by attach, and detaches it from the process’s
memory space, returning 0.
- By default, detaching the memory must succeed or an FBB::Exception
is thrown. Throwing an exception on failure can be prevented by passing
false as the member’s second argument.
- o
- size_t size(int id):
The size (in bytes) of shared memory data block having ID id is
returned.
- An FBB::Exception is thrown if the size of segment id could
not be determined.
bobcat/sharedsegment - defines the class interface
bobcat(7), chmod(1), isharedstream(3bobcat),
osharedstream(3bobcat), sharedblock(3bobcat),
sharedcondition(3bobcat), sharedmemory(3bobcat),
sharedmutex(3bobcat), sharedpos(3bobcat),
sharedreadme(7bobcat), sharedstream(3bobcat),
sharedbuf(3bobcat)
- o
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_5.07.00-x.dsc: detached signature;
- o
- bobcat_5.07.00-x.tar.gz: source archive;
- o
- bobcat_5.07.00-x_i386.changes: change log;
- o
- libbobcat1_5.07.00-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_5.07.00-x_*.deb: debian package containing the
libraries, headers and manual pages;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).