includefile(include/header)

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

manpagename(FBB::SharedSegment)(Shared Memory data structure)

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

manpagedescription()

    The class bf(FBB::SharedSegment) implements the shared memory data
structure used by Bobcat's shared memory classes. Bobcat's
tt(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
bf(SharedSegment) object not all of its potentially available shared memory is
immediately allocated. Shared memory will be allocated by the
bf(SharedSegment) object once needed (up to a calculated maximum).

As a fictitious example: assume 100 kB of memory is requested, then the
bf(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 bf(SharedSegment) therefore defines a gateway, controlling access to
and allocating required shared memory data segments. The mentioned table
consists of tt(nBlocks SharedBlock) (bf(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 bf(SharedSegment)'s sole responsibility is to offer the
framework as described. When used by a tt(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.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

manpagesection(CONSTRUCTORS)

    No publicly accessible constructors have been defined for
bf(SharedSegment). A static member function tt(create) (see below) is
available, returning a pointer to a shared memory segment, in which a
bf(SharedSegment) has been defined.

manpagesection(OVERLOADED OPERATORS)
    itemization(
    itb(std::ostream &operator<<(std::ostream &out, 
                                    SharedSegment const &sharedData))
       The overloaded insertion operator inserts basic statistics of the
        shared memory data into the tt(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.

    itb(FBB::SharedBlock &operator[](size_t idx))
       Table element tt(idx) of the table of tt(FBB::SharedBlock)
        block IDs is returned. The behavior of the program is undefined if
        tt(idx) is or exceeds tt(nBlocks()).

    )

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

manpagesection(MEMBER FUNCTIONS)
    itemization(
    itb(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
        (bf(chmod)(1)) way to define the access rights for owner, group and
        others.
    
    itb(void clear())
       All the shared memory data blocks are unconditionally deleted and
        tt(nReadable) returns 0 (the shared memory data blocks are not locked
        prior to deleting them). After calling tt(clear) all allocated 
        bf(SharedSegment)'s shared memory segments have ceased to exist and
        can no longer be used.

    itb(void lock(size_t idx) const)
       Access to shared data segment tt(idx) is locked. This member itself
        does not support recursive locking.

    itb(size_t nBlocks() const)
       Returns the number of shared memory data blocks that can be used by the
        bf(FBB::SharedSegment) object.

    itb(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 bf(SharedSegment) object.

        An tt(FBB::Exception) is thrown if the shared memory data segment
        could not be allocated.

    itb(std::streamsize nReadable() const)
       Returns the number of characters (bytes) that can be read from the
        beginning of the shared memory.
    
    itb(void nReadableLock() const)
       When returning from this member function a lock has been obtained of
        bf(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 bf(SharedSegment) object.

    itb(void nReadableUnlock() const)
       This member function releases the lock previously acquired by
        tt(nReadableLock).

    itb(size_t segmentSize() const)
       Returns the size (in bytes) of the shared memory data blocks. The
        bf(SharedSegment) object can accommodate at most tt(segmentSize() *
        nBlocks()) bytes.

    itb(bool truncate(std::streamsize offset))
       After calling tt(nReadableLock), 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) has not been changed. Before returning
        tt(nReadableUnlock) is called.

    itb(void unlock(size_t idx) const)
       Releases the lock on the shared memory data segment tt(idx). If the
        current process does not own the lock of shared memory data block
        tt(idx) nothing happens and the function immediately returns.

    itb(void updateNreadable(std::streamsize offset))
       The number of bytes that can be retrieved from the shared memory is
        updated to tt(max(nReadable(), offset)). 
    )

manpagesection(STATIC MEMBER FUNCTIONS)

    itemization(
    itb(void *attach(int id))
       Returns the address of shared memory segment tt(id), mapped to the
        calling process's memory area.

        An tt(FBB::Exception) is thrown if the shared memory data segment
        could not be attached.

    itb(SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize, 
                              size_t access)) 
       Returns a pointer to a newly created  bf(SharedSegment) object,
        defined in the computer's shared memory. 

       The created shared memory's ID is stored at tt(*id). The remaining
        arguments define the potential number of shared memory data blocks
        (tt(nBlocks)); the size of these data blocks (tt(segmentSize)); and
        the shared memory's access rights (tt(access), using the well-known
        octal value representation as used by (bf(chmod)(1)) to define access
        rights for the owner, the group and others).

        An tt(FBB::Exception) is thrown if the shared memory data segment
        could not be created.

    itb(void deleteSegment(int id))
       The shared memory segment having ID tt(id) is deleted. After calling
        tt(deleteSegment) shared memory segment tt(id) doesn't exist
        anymore. The tt(id) can be the shared memory ID of any segment for
        which the current user has write permissions.

        An tt(FBB::Exception) is thrown if shared memory data segment tt(id)
        could not be deleted.

    itb(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 tt(attach), and detaches it from the process's memory
        space, returning 0. 

        By default, detaching the memory must succeed or an bf(FBB::Exception)
        is thrown. Throwing an exception on failure can be prevented by
        passing tt(false) as the member's second argument.

    itb(size_t size(int id))
       The size (in bytes) of shared memory data block having ID tt(id) is
        returned.

        An tt(FBB::Exception) is thrown if the size of segment tt(id) could
        not be determined.
    )

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

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

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

manpagebugs()
    None Reported.

includefile(include/trailer)


