includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(MemoryREADME)(7bobcat)(_CurYrs_)
                    (libbobcat-dev__CurVers_)
                    (Bobcat Memory Segments README)

manpagename(MemoryREADME)(Bobcat's classes accessing memory segments)

manpagedescription()

The following classes accessing memory segments are available:

itemization(
    it() bf(MemoryAccess)(3bobcat)

The class bf(MemoryAccess)(3bobcat) defines an object interfacing to a shared
memory segment (cf. bf(shmget)(2)). If offers functionality to set and
retrieve its tt(id), and write and read bytes from its shared memory segment.
bf(MemoryAccess) objects are used by bf(MemoryBridge)(3bobcat) objects keeping
track of which segments actually contain the data bytes.

bf(MemoryAccess) objects are used by bf(MemoryBridge) and are normally not
directly constructed by user programs.

    it() bf(MemoryBridge)(3bobcat)

The class bf(MemoryBridge) (cf. figure tt(images/sharedsegment1.jpg))
interfaces to shared memory using bf(MemoryAccess) objects. Its main member
function is the static member tt(create), returning a pointer to a newly
allocated tt(MemoryMemory) object.

The member tt(create) receives as its input parameters the number of blocks,
the size of the segments allocated by bf(MemoryBridge), and the segment's
access mode (as used by, e.g., bf(chmod)(1)). It returns a pointer to the
allocated tt(MemoryBridge), and its ID (set using a pointer to an tt(int),
passed as its first parameter).

Although the bf(MemoryBridge) class defines an array of a single
bf(MemoryAccess)(3bobcat) object, in fact it will contain tt(d_nAccesss)
bf(MemoryAccess) objects. The member tt(create) first allocates a block of raw
memory of the required total size. Next it initializes the first part of this
raw, shared memory, using the tt(MemoryBridge) constructor and placement
new. Next, the remaining amount of raw shared memory is initialized with
tt(d_nAccesss - 1) bf(MemoryAccess) objects, again using placement new
(cf. figure tt(images/sharedsegment2.jpg) in the source distribution).

COMMENT(
    it() bf(MemoryPos)(3bobcat)
The class bf(MemoryPos)(3bobcat) monitors position information in the shared
memory segments managed by bf(MemoryBridge) objects. bf(MemoryPos) only has a
default constructor, but offers a bf(reset) member receiving at construction
time a pointer to a bf(MemoryBridge) object.

    it() bf(MemoryMemory)(3bobcat)

The class bf(MemoryMemory)(3bobcat) offers the standard interface to
shared memory, defining members like tt(read, get, write) and tt(put). It
interfaces to a tt(MemoryBridge) object, and uses a tt(MemoryPos) object to
keep track of the tt(MemoryMemory's) offsets.

A bf(MemoryMemory) object itself resides in a program's working memory, and not
in the computer's shared memory area. At any time the bf(MemoryMemory) object
only loads at most one actual block of the shared memory block managed by
bf(MemoryBridge). The current position in the shared memory managed by
bf(MemoryBridge) is monitored by the bf(MemoryMemory)'s tt(MemoryAccess d_pos)
member.
END COMMENT)

Following read/write operations the offset is updated accordingly. There's
only one offset, which is used by tt([IO]?MemoryStream) objects when
requesting or updating offsets. a bf(MemoryMemory) object offers safeguards
against inappropriate use. E.g., if no memory has been allocated yet it may
thow exceptions. Also, offsets can never exceed the tt(MemoryMemory's) maximum
possible offset.

    it() bf(MemoryBuf)(3bobcat)

The class bf(MemoryBuf) implements a tt(std::streambuf) specialization
interfacing to a tt(MemoryMemory) object. In addition to a default constructor
which is an empty stub the class offers constructors which immediately
interface to a tt(MemoryBridge) object.

    it() bf(MemoryStream)(3bobcat)

The bf(MemoryStream) class offers stream-facilities operating on shared memory
maintained by a tt(MemoryBuf) object.
)

An overview of currently defined shared memory segments is shown by the
command tt(ipcs -ma). To erase a defined shared memory segment the command
tt(ipcrm -m <id>) can be used, where tt(<id>) is the shared memory segment's
ID.


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

manpagesection(FILES)

    Images referred to in this man-page are located in the source distribution
in tt(bobcat/documents/images), or they can be found in the standard location
of documentation files in your distribution (e.g., they are located in
tt(/usr/share/doc/libbobcat6/images)).


manpageseealso()
    bf(bobcat)(7), bf(ipcs)(1), bf(ipcrm)(1),
        bf(memoryaccess)(3bobcat),
        bf(memorybridge)(3bobcat),
        bf(memorybuf)(3bobcat),
        bf(memorystream)(3bobcat)

COMMENT(
        bf(memoryid)(3bobcat),
END)

manpagebugs()
    None Reported.

includefile(include/trailer)
