includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::SharedMemory)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Shared Memory Memory)

manpagename(FBB::SharedMemory)(Shared Memory memory structure)

manpagesynopsis()
    bf(#include <bobcat/sharedmemory>)nl()
    Linking option: tt(-lbobcat ) 

manpagedescription()

    The class bf(FBB::SharedMemory) implements a usable interface to a shared
memory segment made available by tt(FBB::SharedSegment) and monitored by
tt(FBB::SharedPos). It is the main building block for
tt(FBB::SharedBuf), defining the `device' to which
tt(FBB::SharedBuf) interfaces. All shared memory related I/O should be
performed by bf(FBB::SharedMemory) objects, which are true objects, not
themselves residing in shared memory. 

An bf(FBB::SharedMemory) object defines, connects to and manages access to
shared memory, encapsulating all raw shared memory operations. In addition to
the class bf(FBB::SharedMemory) the header file tt(bobcat/sharedmemory) also
defines a bf(struct SharedEnum__) defining bf(enum SizeUnit) within the
namespace tt(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
bf(SharedMemory) object not all of its potentially available shared memory is
immediately allocated. Shared memory will be allocated by the bf(SharedMemory)
object once needed (up to a calculated maximum).

As a fictitious example: assume 100 kB of memory is requested. The
bf(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 bf(ipcs)(1) and bf(ipcrm)(1)). The member
tt(id) returns the ID of the shared memory currently monitored by an
bf(FBB::SharedMemory) object.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(FBB::SharedEnum__)

    The bf(struct SharedEnum__) is a wrapper struct around bf(enum SizeUnit),
which is available through inheritance in several bf(FBB::Shared*) classes,
and offers symbolic constants defining standard memory sizes. The bf(enum
SizeUnit) defines the following symbolic constants:
        itemization(
        it() bf(kB), representing 1024 (2**10) bytes of memory;
        it() bf(MB), representing 1048576 (2**20) bytes of memory;
        it() bf(GB), representing 1073741824 (2**30) bytes of memory
        )

manpagesection(CONSTRUCTORS, DESTRUCTOR)

    itemization(
    itb(SharedMemory())
       The default constructor defines an empty stub, which cannot immediately
        be used.  As the bf(SharedMemory) class supports move assignment,
        empty stubs can easily be (re)configured at any time after their
        construction.

    itb(SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600))
       This constructor creates a shared memory segment having a capacity of
        at least tt(maxSize * sizeUnit) bytes. The shared memory's access
        rights are defined by the tt(access) parameter, using the well-known
        (bf(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 tt(FBB::Exception) is thrown.

    itb(SharedMemory(int id))
       This constructor connects to a shared memory segment having ID
        tt(id). If construction succeeds the shared memory is ready for
        use. If construction fails (e.g., no shared memory segment having ID
        tt(id) exists), an tt(FBB::Exception) is thrown.

    itb(~SharedMemory())
       The destructor detaches any attached shared memory segments from
        the bf(FBB::SharedMemory) object. If the shared memory segment is
        currently locked by the bf(FBB::SharedMemory) object, the lock is
        removed.
    )

    Copy and move constructors (and assignment operators) are not available.


manpagesection(OVERLOADED OPERATORS)
    itemization(
    itb(std::ostream &operator<<(std::ostream &out, 
                                    SharedMemory const &sharedMemory))
       The overloaded insertion operator inserts information about the
        tt(SharedMemory) object into the provide tt(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.

    itb(SharedMemory &operator=(SharedMemory &&rhs))
       The overloaded move assignment operator is available. It is used to
        (re)define the shared memory segment an bf(FBB::SharedMemory) object
        is interfacing with.
    )

manpagesection(MEMBER FUNCTIONS)
    itemization(
    itb(size_t blockOffset() const)
       The offset within the shared segment data block matching tt(offset)'s
        return value is returned. 0 is returned if the bf(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).

    itb(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 tt(clear) the shared memory The
        bf(FBB::SharedMemory) object is effectively re-initialized, with
        tt(offset) and tt(nReadable) returning 0.

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(size_t dataSegmentSize() const)
       Returns the size (in bytes) of shared memory data block. 0 is returned
        if the bf(SharedMemory) object has not yet been connected to a shared
        memory block.

    itb(int get())
       First the bf(FBB::SharedMemory) object calls tt(lock) to lock the
        shared memory segment. Next the character at tt(offset) is retrieved
        and tt(offset) is incremented. Then tt(unlock) is called, and the
        retrieved character is returned. If tt(offset) is at least equal to
        tt(nReadable, EOF) is immediately returned.

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int id() const)
       The ID of the shared memory segment is returned. Following tt(kill)
        tt(id) returns -1, indicating that the shared segment cannot be used
        anymore (note that tt(operator=) can be used to re-initialize the
        bf(FBB::SharedMemory) object).

    itb(SharedType *install(std::streamsize *offset, 
                           Params &&...params))
       This member was implemented as a member template, using tt(typename
        SharedType) and tt(typename ...Params), allowing perfect forwarding of
        arguments to tt(SharedType)'s constructor.

        This member installs a tt(SharedType) object at bf(SharedMemory's) at
        bf(SharedMemory)'s first available offset: either at the current
        offset, or (if tt(SharedType's) size is too big to fit in the current
        data block at offset) at the first byte of the next tt(SharedSegment)
        shared data block.

        The actual offset where the tt(SharedType) object is installed is
        returned in tt(*offset), unless a tt(nullptr) is passed as
        tt(install's) first argument.

        A pointer to the installed tt(SharedType) is returned, with
        tt(shmem.offset) pointing just beyond tt(SharedType's) last byte. 

        The tt(SharedType) object is installed using placement new. E.g., the
        following example illustrates how a bf(SharedMutex)(3bobcat) object
        can be installed at the first possible 
        location of tt(SharedMemory shmem):
            verb(
    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 tt(Mutex) pointed at by
        tt(mutexPtr) use tt(mutexPtr->~SharedMutex()).

        An tt(FBB::Exception) is thrown if tt(shmem) could not install the
        object in its shared memory data blocks.

    itb(void kill())
       Without locking the shared memory all shared memory controlled by the
        bf(SharedMemory) object is deleted. The bf(SharedMemory) object is
        unusable after returning from tt(kill), with its tt(id) member returns
        -1. Nothing happens if this member is called when the bf(SharedMemory)
        object has not yet been connected to a shared memory block.

    itb(std::streamsize maxOffset() const)
       The maximum possible offset that can be used with the shared memory
        segment is returned. The members tt(offset) and tt(nReadable) never
        exceed the value returned by tt(maxOffset). 0 is returned if the
        bf(SharedMemory) object has not yet been connected to a shared memory
        block.

    itb(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 bf(SharedMemory)
        object has not yet been connected to a shared memory block.
    
    itb(std::streamsize offset() const)
       The offset within the shared memory segment (i.e., relative to the
        segment's tt(ios::beg) position) is returned. 0 is returned if the
        bf(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).

    itb(char *ptr())
        Returns 0 if tt(offset() == maxOffset()). Otherwise it returns a
        pointer to the character at index tt(offset) within the shared memory
        segment.

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int put(int ch))
       After locking the appropriate shared data segment, tt(ch) is written at
        position tt(offset), incrementing tt(offset) thereafter. If tt(ch ==
        EOF, EOF) is immediately returned.

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int read(Type *value))
       This member was implemented as a member template. It calls
        the next member, casting tt(Type *) to tt(char *), and using
        tt(sizeof(Type)) as its second argument.  The number of
        bytes actually read is returned. This member returns -1 if
        initially tt(offset) was at least equal to tt(nReadable).

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int read(char *data, std::streamsize len))
       While locking the appropriate shared data segment(s) at most tt(len)
        bytes are read from the shared memory, starting at tt(offset). The
        bytes read from shared memory are stored at tt(data).  The number of
        bytes actually read is returned. This member returns -1 if
        initially tt(offset) was at least equal to tt(nReadable).
              
        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(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
        bf(SharedMemory)'s offset to tt(offset) (relative to tt(origin)), it
        calls the first tt(read) member, passing it tt(value). The number of
        bytes actually read is returned. This member returns -1 if initially
        tt(offset) was at least equal to tt(nReadable).
              
        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(void remove())
       The shared memory is locked, after which all shared memory controlled
        by the bf(FBB::SharedMemory) object is deleted. The
        bf(FBB::SharedMemory) object is unusable after returning from
        tt(remove).

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(std::ios::pos_type seek(std::ios::off_type offset, 
                            std::ios::seekdir origin = std::ios::beg))
       Moves the tt(offset) position relative to tt(way). The value -1 is
        returned when seeking before offset 0 or beyond tt(maxOffset),
        otherwise the offset relative to the begin location of the shared
        memory (i.e, tt(offset) for tt(origin == ios::beg)) is returned.  0 is
        returned if the bf(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).

    itb(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 bf(SharedMemory) object has not yet been connected to a shared
        memory block (or if the no characters can currently be read).

    itb(void swap(SharedMemory &other))
       The current and other bf(FBB::SharedMemory) objects are swapped.

    itb(bool truncate(std::streamsize offset))
       If tt(offset) is not exceeding the value returned by tt(nReadable)
        tt(nReadable) is changed to tt(offset) and tt(true) is
        returned. Otherwise tt(false) is returned, and the value returned by
        tt(nReadable) is not changed. 

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int write(Type const *value))
       This member was implemented as a member template. It calls the next
        member, casting tt(Type const *) to tt(char const *), and using
        tt(sizeof(Type)) as its second argument.  The number of bytes actually
        written is returned. This member returns -1 if initially tt(offset)
        was at least equal to tt(maxOffset).
              
        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(int write(char const *data, std::streamsize len))
       The bf(FBB::SharedMemory) object calls tt(lock) to lock the shared
        memory, and writes at most tt(len) bytes into the shared memory,
        starting at tt(offset). Next, tt(unlock) is called. The number of
        bytes actually written is returned. The member function returns -1 if
        initially tt(offset) is equal to tt(maxOffset).

        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.

    itb(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
        bf(SharedMemory)'s offset to tt(offset) (relative to tt(origin)), it
        calls the first tt(write) member, passing it tt(value). The number of
        bytes actually written is returned. This member returns -1 if
        initially tt(offset) was at least equal to tt(maxOffset).
              
        An tt(FBB::Exception) is thrown if the bf(SharedMemory) object has not
        yet been connected to a shared memory block.
    )



manpagesection(EXAMPLE)
    See the bf(sharedstream)(3bobcat) man page.

manpagefiles()
    em(bobcat/sharedmemory) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(chmod)(1), bf(ipcs)(1), bf(ipcrm)(1),
        bf(isharedstream)(3bobcat),
        bf(osharedstream)(3bobcat),
        bf(sharedblock)(3bobcat), 
        bf(sharedcondition)(3bobcat), 
        bf(sharedmutex)(3bobcat), 
        bf(sharedpos)(3bobcat), 
        bf(sharedreadme)(7bobcat),
        bf(sharedsegment)(3bobcat),
        bf(sharedstream)(3bobcat), 
        bf(sharedbuf)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)


