--- name: "sharedreadme" section: "7bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/sharedreadme" --- # sharedreadme(7bobcat) Description of Bobcat’s shared memory classes ## NAME SharedREADME - Description of Bobcat’s shared memory classes ## DESCRIPTION The following shared memory classes are available: - o **SharedBlock**(3bobcat) - The class **SharedBlock**(3bobcat) defines a small object consisting of a **SharedMutex** and a (shared segment) id. If offers functionality to set and retrieve the id, and to lock and unlock the **SharedMutex**. **SharedBlock** objects are used by **SharedSegment**(3bobcat) objects to keep track of which segments actually contain the shared memory data. It’s a bookkeeping helper class. - - o **SharedSegment**(3bobcat) - The class **SharedSegment** (cf. figure *images/sharedsegment1.jpg*) interfaces to actual shared memory. Its main member function is the static member *create*, returning a pointer to a newly allocated *SharedMemory* object. - The member *create* receives as its input parameters the number of blocks, the size of the segments allocated by **SharedSegment**, and the segment’s access mode (as used by, e.g., [**chmod**(1)](/chmod/1.md)). It returns a pointer to the allocated *SharedSegment*, and its ID (set using a pointer to an *int*, passed as its first parameter). - Although the **SharedSegment** class defines an array of a single **SharedBlock**(3bobcat) object, in fact it will contain *d\_nBlocks* **SharedBlock** objects. The member *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 *SharedSegment* constructor and placement new. Next, the remaining amount of raw shared memory is initialized with *d\_nBlocks - 1* **SharedBlock** objects, again using placement new (cf. figure *images/sharedsegment2.jpg*). - o **SharedPos**(3bobcat) - The class **SharedPos**(3bobcat) monitors position information in the shared memory segments managed by **SharedSegment** objects. **SharedPos** only has a default constructor, but offers a **reset** member receiving at construction time a pointer to a **SharedSegment** object. - - o **SharedMemory**(3bobcat) - The class **SharedMemory**(3bobcat) offers the standard interface to shared memory, defining members like *read, get, write* and *put*. It interfaces to a *SharedSegment* object, and uses a *SharedPos* object to keep track of the *SharedMemory’s* offsets. - A **SharedMemory** object itself resides in a program’s working memory, and not in the computer’s shared memory area. At any time the **SharedMemory** object only loads at most one actual block of the shared memory block managed by **SharedSegment**. The current position in the shared memory managed by **SharedSegment** is monitored by the **SharedMemory**’s *SharedBlock d\_pos* member. - Following read/write operations the offset is updated accordingly. There’s only one offset, which is used by *\[IO\]?SharedStream* objects when requesting or updating offsets. a **SharedMemory** 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 *SharedMemory’s* maximum possible offset. - - o **SharedMutex**(3bobcat) - The class **SharedMutex** implements a non-recursive mutex that can be stored in shared memory. It merely offers *lock* and *unlock* members. Within one thread *lock* should never be called repeatedly unless *unlock* is called first. The *unlock* member may safely repeatedly be called; once the mutex has been unlocked, repeated requests to unlock the mutex are simply ignored. When a **SharedMutex** is destroyed it calls *unlock*. Use *SharedMemory’s install* member to define a **SharedMutex** object in shared memory, and use *ptr-\>~SharedMutex()* (with *SharedMutex \*ptr* pointing at the *SharedMutex* object) to destroy it again. - - o **SharedCondition**(3bobcat) - The class **SharedCondition** implements a condition variable and an associated mutex, both created in shared memory controlled by a **SharedMemory** object. It offers all the functionality of *std::condition\_variable*. A **SharedCondition** object itself is defined in a thread’s working memory, but interfaces to a *\`Condition’* object containing a condition variable and a mutex which are installed in shared memory. The size of this *\`Condition’* object is returned by the static member *SharedCondition::size*. **SharedCondition** members ensure that the thread has access to the *\`Condition’* object, and that the shared memory’s offset has not changed when returning from the **SharedCondition’s** members. - - o **SharedBuf**(3bobcat) - The class **SharedBuf** implements a *std::streambuf* specialization interfacing to a *SharedMemory* object. In addition to a default constructor which is an empty stub the class offers constructors which immediately interface to a *SharedMemory* object, as well as a member to (re)associate a **SharedBuf** object with a *SharedMemory* object. - - o **SharedStream, ISharedStream, OSharedStream**(3bobcat) - These stream classes offer stream-facilities operating on shared memory maintained by a *SharedMemory* object. The **SharedStream** class uses the *SharedMemory’s seek* member for both *seekp* and *seekg*, and uses *SharedMemory’s offset* member for both *tellp* and *tellg*. All shared stream objects, including **ISharedStream**, offer a member to initialize a *SharedCondition* - An overview of currently defined shared memory segments is shown by the command *ipcs -ma*. To remove a defined shared memory segment the command *ipcrm -m \* can be used, where *\* is the shared memory segment’s ID. ## EXAMPLE See the [**sharedstream**(3bobcat)](/sharedstream/3bobcat.md) man page. ## FILES Images referred to in this man-page are located in the source distribution in *bobcat/documents/images*, or they can be found in the standard location of documentation files in your distribution (e.g., they are located in */usr/share/doc/libbobcat6/images*). ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**ipcs**(1)](/ipcs/1.md), [**ipcrm**(1)](/ipcrm/1.md), [**isharedstream**(3bobcat)](/isharedstream/3bobcat.md), [**osharedstream**(3bobcat)](/osharedstream/3bobcat.md), [**sharedblock**(3bobcat)](/sharedblock/3bobcat.md), [**sharedcondition**(3bobcat)](/sharedcondition/3bobcat.md), [**sharedmemory**(3bobcat)](/sharedmemory/3bobcat.md), [**sharedmutex**(3bobcat)](/sharedmutex/3bobcat.md), [**sharedpos**(3bobcat)](/sharedpos/3bobcat.md), [**sharedsegment**(3bobcat)](/sharedsegment/3bobcat.md), [**sharedstream**(3bobcat)](/sharedstream/3bobcat.md), [**sharedbuf**(3bobcat)](/sharedbuf/3bobcat.md) ## BUGS None Reported. ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## 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**).