FBB::SharedMemory(3bobcat)

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

✨ NAME ✨

FBB::SharedMemory — Shared Memory memory structure. And yes bestie, this is the manual for FBB::SharedMemory(3bobcat), so buckle up. 💖

🌸 SYNOPSIS 🌸

#include <bobcat/sharedmemory>

Linking option: -lbobcat

🦋 DESCRIPTION 🦋

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

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

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

💜 NAMESPACE 💜

FBB

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

👑 INHERITS FROM 👑

FBB::SharedEnum__

The struct SharedEnum__ is a wrapper struct around enum SizeUnit, which is available through inheritance in several FBB::Shared* classes, and offers symbolic constants defining standard memory sizes. The enum SizeUnit defines the following symbolic constants:

  • kB, representing 1024 (2**10) bytes of memory;
  • MB, representing 1048576 (2**20) bytes of memory;
  • GB, representing 1073741824 (2**30) bytes of memory

🎀 CONSTRUCTORS, DESTRUCTOR 🎀

  • SharedMemory() — The default constructor defines an empty stub, which cannot immediately be used. As the SharedMemory class supports move assignment, empty stubs can easily be (re)configured at any time after their construction. It’s giving “blank canvas, but make it move-assignable.” ✨
  • SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600) — This constructor creates a shared memory segment having a capacity of at least maxSize * sizeUnit bytes. The shared memory’s access rights are defined by the access parameter, using the well-known (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 FBB::Exception is thrown. No cap, those octal perms are doing the most. 💅
  • SharedMemory(int id) — This constructor connects to a shared memory segment having ID id. If construction succeeds the shared memory is ready for use. If construction fails (e.g., no shared memory segment having ID id exists), an FBB::Exception is thrown. Like sliding into someone else’s shared-memory DMs, but with an int. 😭
  • ~SharedMemory() — The destructor detaches any attached shared memory segments from the FBB::SharedMemory object. If the shared memory segment is currently locked by the FBB::SharedMemory object, the lock is removed. Cleanup era. 🧚

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

⭐ OVERLOADED OPERATORS ⭐

  • std::ostream &operator<<(std::ostream &out, SharedMemory const &sharedMemory) — The overloaded insertion operator inserts information about the SharedMemory object into the provided 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. Basically a whole vibe report for your shared memory. 🌈
  • SharedMemory &operator=(SharedMemory &&rhs) — The overloaded move assignment operator is available. It is used to (re)define the shared memory segment an FBB::SharedMemory object is interfacing with. Reinventing yourself, but for shared memory segments. 👑

✨ MEMBER FUNCTIONS ✨

okay bestie, here's the whole roster of member functions, and yes we're going through every single one because you deserve the full tea 💅

  • size_t blockOffset() const — returns the offset within the shared segment data block that matches what offset gives you back. 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet (or if the offset just happens to be sitting at the block's offset 0). no cap.
  • void clear() — first, the shared memory gets locked. then all shared data segments are deleted, and the shared memory's own data gets reset to show it's completely empty. after that, the shared memory segment is unlocked again. when clear returns, the FBB::SharedMemory object is effectively re-initialized, with offset and nReadable both returning 0. slay. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • size_t dataSegmentSize() const — returns the size (in bytes) of the shared memory data block. 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int get() — first the FBB::SharedMemory object calls lock to lock the shared memory segment. next, the character at offset is retrieved and offset gets incremented. then unlock is called, and the retrieved character is returned. if offset is at least equal to nReadable, EOF is immediately returned. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int id() const — returns the ID of the shared memory segment. after kill, id returns -1, which means the shared segment can't be used anymore (btw operator= can be used to re-initialize the FBB::SharedMemory object if you need to).
  • SharedType *install(std::streamsize *offset, Params &&...params) — this one was implemented as a member template, using typename SharedType and typename ...Params, which allows perfect forwarding of arguments to SharedType's constructor. it installs a SharedType object at SharedMemory's first available offset: either at the current offset, or (if SharedType's size is too big to fit in the current data block at offset) at the first byte of the next SharedSegment shared data block.

the actual offset where the SharedType object is installed is returned in *offset, unless a nullptr is passed as install's first argument. a pointer to the installed SharedType is returned, with shmem.offset pointing just beyond SharedType's last byte.

the SharedType object is installed using placement new. for example, here's how you'd install a SharedMutex(3bobcat) object at the first possible location of SharedMemory shmem:

std::streamsize offset;
FBB::SharedMutex *mutexPtr = shmem.install<FBB::SharedMutex>(&offset);

if the installed object needs to be destroyed, its destructor must be explicitly called. for example, to destroy the Mutex pointed at by mutexPtr, use mutexPtr->~SharedMutex(). an FBB::Exception is thrown if shmem couldn't install the object in its shared memory data blocks.

  • void kill() — without locking the shared memory, all shared memory controlled by the SharedMemory object is deleted. the SharedMemory object is unusable after returning from kill, and its id member returns -1. nothing happens if this member is called when the SharedMemory object hasn't been connected to a shared memory block yet.
  • std::streamsize maxOffset() const — returns the maximum possible offset that can be used with the shared memory segment. the members offset and nReadable never exceed the value returned by maxOffset. 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet.
  • std::streamsize nReadable() const — returns the number of characters (bytes) that can be read from the beginning of the shared memory. 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet.
  • std::streamsize offset() const — returns the offset within the shared memory segment (so, relative to the segment's ios::beg position). 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet (or if the offset just happens to be at the shared memory's offset 0).
  • char *ptr() — returns 0 if offset() == maxOffset(). otherwise it returns a pointer to the character at index offset within the shared memory segment. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int put(int ch) — after locking the appropriate shared data segment, ch is written at position offset, incrementing offset afterwards. if ch == EOF, EOF is immediately returned. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int read(Type *value) — this member was implemented as a member template. it calls the next member, casting Type * to char *, and using sizeof(Type) as its second argument. the number of bytes actually read is returned. this member returns -1 if initially offset was at least equal to nReadable. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int read(char *data, std::streamsize len) — while locking the appropriate shared data segment(s), at most len bytes are read from the shared memory, starting at offset. the bytes read from shared memory are stored at data. the number of bytes actually read is returned. this member returns -1 if initially offset was at least equal to nReadable. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • 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 SharedMemory's offset to offset (relative to origin), it calls the first read member, passing it value. the number of bytes actually read is returned. this member returns -1 if initially offset was at least equal to nReadable. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • void remove() — the shared memory is locked, after which all shared memory controlled by the FBB::SharedMemory object is deleted. the FBB::SharedMemory object is unusable after returning from remove. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • std::ios::pos_type seek(std::ios::off_type offset, std::ios::seekdir origin = std::ios::beg) — moves the offset position relative to way. the value -1 is returned when seeking before offset 0 or beyond maxOffset, otherwise the offset relative to the begin location of the shared memory (i.e., offset for origin == ios::beg) is returned. 0 is returned if the SharedMemory object hasn't been connected to a shared memory block yet (or if the offset just happens to be at the shared memory's offset 0).
  • std::streamsize showmanyc() const — returns the number of characters that can be read from the current shared segment data block. this member interrogates the number of readable characters in the shared memory segment. heads up: 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 SharedMemory object hasn't been connected to a shared memory block yet (or if no characters can currently be read).
  • void swap(SharedMemory &other) — swaps the current and other FBB::SharedMemory objects. iconic.
  • bool truncate(std::streamsize offset) — if offset is not exceeding the value returned by nReadable, nReadable is changed to offset and true is returned. otherwise false is returned, and the value returned by nReadable is not changed. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int write(Type const *value) — this member was implemented as a member template. it calls the next member, casting Type const * to char const *, and using sizeof(Type) as its second argument. the number of bytes actually written is returned. this member returns -1 if initially offset was at least equal to maxOffset. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • int write(char const *data, std::streamsize len) — the FBB::SharedMemory object calls lock to lock the shared memory, and writes at most len bytes into the shared memory, starting at offset. next, unlock is called. the number of bytes actually written is returned. the member function returns -1 if initially offset is equal to maxOffset. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.
  • 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 SharedMemory's offset to offset (relative to origin), it calls the first write member, passing it value. the number of bytes actually written is returned. this member returns -1 if initially offset was at least equal to maxOffset. an FBB::Exception is thrown if the SharedMemory object hasn't been connected to a shared memory block yet.

🌸 EXAMPLE 🌸

see the sharedstream(3bobcat) man page. that's the vibe. 💖

🎀 FILES 🎀

  • bobcat/sharedmemory — defines the class interface

🔗 SEE ALSO

ok bestie, when you're done here and you want MORE reading (and honestly, same), go check these out 💖:

it's giving "shared everything" fr fr 🌸

🐛 BUGS

None Reported.

literally flawless behavior?? no cap, nothing reported. the vibe check has been passed 👑

📁 BOBCAT PROJECT FILES

Debian Bobcat project files, for the Debian girlies 🎀:

  • libbobcat6 — the debian package containing the shared library, changelog and copyright note
  • libbobcat-dev — the 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'.

like… the naming? iconic. ate and left no crumbs ✨

This is free software, distributed under the terms of the GNU General Public License (GPL).

free as in freedom bestie, go wild 🦋

👑 AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl).

the main character who wrote all of this 💜

and that's a wrap, bestie!! this whole page came from the libbobcat-dev_6.07.01 source, dated 2005-2025 — a whole two decades of shared memory excellence, we love to see it 🫶 now go make some segments and slay 💅🌈

📦 where this page comes from