FBB::SharedSegment(3bobcat)

📦
version 6.07.01 · 5 versions
, in debian trixie, ubuntu questing

💖 FBB::SharedSegment 💖

okay bestie, welcome to the <bobcat/sharedsegment> era — this is the manual page for the shared memory data structure, straight out of section 3 of the Bobcat manuals ✨

🎀 NAME 🎀

FBB::SharedSegment — the Shared Memory data structure, no cap 💅

🌸 SYNOPSIS 🌸

#include <bobcat/sharedsegment>
Linking option: -lbobcat

🦋 DESCRIPTION 🦋

okay so the class FBB::SharedSegment implements the shared memory data structure that Bobcat's shared memory classes use. Bobcat's SharedMemory class accesses or defines a shared memory segment, and it controls all its read and write operations.

here's the tea ☕ — the amount of shared memory you request is always a lower bound to the maximum amount of shared memory that might eventually become available. So when you define a SharedSegment object, not all of its potentially available shared memory gets allocated right away. The SharedSegment object allocates shared memory once it's needed (up to a calculated maximum). it's giving lazy loading but make it memory 🫶

as a fictitious example: say 100 kB of memory is requested, then the SharedSegment object maintains a table of, e.g., 10 entries, each one controlling access to a shared memory block of 10 kB. Those 10 kB blocks aren't immediately allocated — they become available once the program reads from or writes to addresses located in these data segments. iconic behaviour honestly.

so the class SharedSegment defines a gateway, controlling access to and allocating the required shared memory data segments. That table we mentioned consists of nBlocks SharedBlock (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 their shared memory data segment has not yet been allocated — or they contain the IDs of defined shared memory data segments. yesss the -1 is the "not yet" flag, remember that 💀

The class SharedSegment's sole responsibility is to offer the framework as described. When it's used by an FBB::SharedMemory object, different processes may gain access to different parts of the shared memory data without interfering with each other's read and write actions. teamwork makes the dream work fr fr 🌈

✨ NAMESPACE ✨

FBB

All constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB. periodt 💅

🧚 INHERITS FROM 🧚

-

(yeah bestie, nothing. it inherits from nobody, it's self-made 👑)

💜 CONSTRUCTORS 💜

No publicly accessible constructors have been defined for SharedSegment. Instead there's a static member function create (peep below) that returns a pointer to a shared memory segment, in which a SharedSegment has been defined. so you don't just new this thing, you create it ✨

🔥 OVERLOADED OPERATORS 🔥

  • std::ostream &operator<<(std::ostream &out, SharedSegment const &sharedData) — this overloaded insertion operator inserts basic statistics of the shared memory data into the ostream object. What stats, you ask? Info 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. it's basically the receipts 📊
  • FBB::SharedBlock &operator[](size_t idx) — returns table element idx of the table of FBB::SharedBlock block IDs. > ⚠️ the behavior of the program is undefined if idx is or exceeds nBlocks(). so like, don't do that bestie, please 🙈

Copy and move constructors (and assignment operators) are not available. not a thing. never was. 💀

🌟 MEMBER FUNCTIONS 🌟

  • 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 (chmod(1)) way to define the access rights for owner, group and others. octal rights, you know the vibe 🔐
  • void clear() — all the shared memory data blocks are unconditionally deleted and nReadable returns 0. and here's the spicy part: the shared memory data blocks are not locked prior to deleting them. After calling clear, all allocated SharedSegment's shared memory segments have ceased to exist and can no longer be used. gone, reduced to atoms 😭
  • void lock(size_t idx) const — access to shared data segment idx is locked. this member itself does not support recursive locking, so no nesting bestie 🔒
  • size_t nBlocks() const — returns the number of shared memory data blocks that can be used by the FBB::SharedSegment object.
  • int newData(size_t idx) — returns the ID of a newly created shared memory data segment. That ID is also stored in the table of shared memory data segments that is maintained by the SharedSegment object.
An FBB::Exception is thrown if the shared memory data segment could not be allocated. 😤
  • std::streamsize nReadable() const — returns the number of characters (bytes) that can be read from the beginning of the shared memory.
  • void nReadableLock() const — when this member function returns, a lock has been obtained of SharedSegment's mutex controlling access to the object's data member storing the number of characters that can be read from the shared memory controlled by the SharedSegment object. locked in 🔐
  • void nReadableUnlock() const — releases the lock previously acquired by nReadableLock. and we're free 🦋
  • size_t segmentSize() const — returns the size (in bytes) of the shared memory data blocks. The SharedSegment object can accommodate at most segmentSize() * nBlocks() bytes. do the math bestie, that's your ceiling 📏
  • bool truncate(std::streamsize offset) — after calling nReadableLock, if offset is not exceeding the value returned by nReadable, then nReadable is changed to offset and true is returned. Otherwise false is returned, and the value returned by nReadable has not been changed. Before returning, nReadableUnlock is called. so either it slays or it doesn't, no in-between 💅
  • void unlock(size_t idx) const — releases the lock on the shared memory data segment idx. If the current process does not own the lock of shared memory data block idx, nothing happens and the function immediately returns. no drama, it just leaves 🌸
  • void updateNreadable(std::streamsize offset) — the number of bytes that can be retrieved from the shared memory is updated to max(nReadable(), offset). it only ever goes up, grow bestie grow 🌱

⭐ STATIC MEMBER FUNCTIONS ⭐

  • void *attach(int id) — returns the address of shared memory segment id, mapped to the calling process's memory area.
An FBB::Exception is thrown if the shared memory data segment could not be attached. 😭
  • SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize, size_t access) — returns a pointer to a newly created SharedSegment object, defined in the computer's shared memory. yesss the birth of a segment 🎀

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

To return the shared segment to the operating system, deleteSegment should be used. don't ghost it, clean up properly 🧹

An FBB::Exception is thrown if the shared memory data segment could not be created.
  • void deleteSegment(int id) — the shared memory segment having ID id is deleted. After calling deleteSegment, shared memory segment id doesn't exist anymore. The id can be the shared memory ID of any segment for which the current user has write permissions.
An FBB::Exception is thrown if shared memory data segment id could not be deleted.
  • 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 attach, and detaches it from the process's memory space, returning 0.

By default, detaching the memory must succeed or an FBB::Exception is thrown. Throwing an exception on failure can be prevented by passing false as the member's second argument. so requireOK = true is the default, and false is your chill mode option 😌

📌 Note that detaching a memory segment does not destroy it. To return a shared segment to the operating system, deleteSegment should be used. detach ≠ delete, write that down bestie 🖊️
  • size_t size(int id) — the size (in bytes) of shared memory data block having ID id is returned.
An FBB::Exception is thrown if the size of segment id could not be determined.

🌈 EXAMPLE 🌈

See the sharedstream(3bobcat) man page. (go read it, it's the main character of the examples ✨)

🍓 FILES 🍓

bobcat/sharedsegment — defines the class interface

💫 SEE ALSO 💫

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

the whole friend group, all linked up 🫶

🙈 BUGS 🙈

None Reported. (we love a flawless queen 💅)

👑 BOBCAT PROJECT FILES 👑

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note;
  • 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. iykyk 🐱

This is free software, distributed under the terms of the GNU General Public License (GPL). free as in freedom bestie 💖

✨ AUTHOR ✨

Frank B. Brokken (f.b.brokken@rug.nl). the icon, the legend 👑

and that's a wrap on libbobcat-dev_6.07.01 🎀 dated 2005-2025, page FBB::SharedSegment(3bobcat) — mwah, go forth and share your memory safely 💅🦋✨

📦 where this page comes from