FBB::SharedMemory(3bobcat)
Shared Memory Memory
(libbobcat-dev_6.06.02)
2005-2024
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::SharedBuf, defining the `device' to which
FBB::SharedBuf 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:
        
        -  kB, representing 1024 (2**10) bytes of memory;
        
-  MB, representing 1048576 (2**20) bytes of memory;
        
-  GB, representing 1073741824 (2**30) bytes of memory
        
CONSTRUCTORS, DESTRUCTOR
    -  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.
 
-  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.
 
-  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.
 
-  ~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 (and assignment operators) are not available.
OVERLOADED OPERATORS
    
    -  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.
 
-  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.
MEMBER FUNCTIONS
    
    -  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 (or if the
        offset happens to be at the block's offset 0).
 
-  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.
 
 
-  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.
 
-  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.
 
 
-  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).
 
-  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.
 
 
-  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.
 
-  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.
 
-  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.
 
-  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 (or if the offset happens to be at the shared memory's offset
        0).
 
-  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.
 
 
-  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.
 
 
-  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.
 
 
-  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.
 
 
-  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.
 
 
-  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.
 
 
-  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 (or if the offset happens to be at the shared
        memory's offset 0).
 
-  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 (or if the no characters can currently be read).
 
-  void swap(SharedMemory &other):
 The current and other FBB::SharedMemory objects are swapped.
 
-  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.
 
 
-  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.
 
 
-  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.
 
 
-  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),
        sharedbuf(3bobcat)
BUGS
    None Reported.
BOBCAT PROJECT FILES
    -  https://fbb-git.gitlab.io/bobcat/: gitlab project page;
    
-  bobcat_6.06.02-x.dsc: detached signature;
    
-  bobcat_6.06.02-x.tar.gz: source archive;
    
-  bobcat_6.06.02-x_i386.changes: change log;
    
-  libbobcat1_6.06.02-x_*.deb: debian package containing the
            libraries;
    
-  libbobcat1-dev_6.06.02-x_*.deb: debian package containing the
            libraries, headers and manual pages;
    
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).