FBB::SharedBuf(3bobcat)

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

💖 FBB::SharedBuf 💖 — from the bobcat manuals, section 3

okay bestie sit DOWN because we're about to talk about the streambuf that talks to shared memory and it's genuinely so cool 🫶

✨ NAME ✨

FBB::SharedBuf — the streambuf that interfaces to shared memory. that's it, that's the whole job 💅

🌸 SYNOPSIS 🌸

#include <bobcat/sharedbuf>
Linking option: -lpthread -lbobcat

like, link it properly or it simply will not vibe with you. no cap.

🦋 DESCRIPTION 🦋

so this class is a specialization of std::streambuf, and what that means is it lets stream classes do actual I/O on shared memory. we're talking std::istream, std::ostream, FBB::ISharedStream, FBB::OSharedStream and FBB::SharedStream — all of them, slaying together. and the way it works is that FBB::SharedBuf objects interface to FBB::SharedMemory objects. iconic behavior honestly.

🎀 NAMESPACE 🎀

FBB

every single constructor, member, operator and manipulator that gets mentioned in this man page lives in the namespace FBB. don't @ me.

🌈 INHERITS FROM 🌈

  • std::streambuf
  • FBB::SharedEnum__ — and if you wanna know about that one, go read sharedmemory(3bobcat), it's all explained there 💜

⭐ SIZEUNIT ENUMERATION ⭐

the enum SizeUnit defines these symbolic constants, and they're your units of memory, bestie:

  • 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 👑

  • SharedBuf() — the default constructor. this one makes a stub SharedBuf object that literally cannot be used to access shared memory right away. so before shared stream classes like FBB::SharedStream can use it, you gotta call its setMemory member first. no setMemory, no shared memory, periodt.
  • SharedBuf(size_t maxSize, SizeUnit sizeUnit, std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600) — this one creates a shared memory segment with a capacity of at least maxSize * sizeUnit bytes. by default the segment is opened for reading and writing. and here's the tea: unlike the open modes for file streams, creating a shared memory stream with open modes ios::in | ios::out is totally OK. in this case the shared memory segment is created, and once info has been written to the shared memory it can be read again too. the shared memory's access rights come from the access parameter, which is interpreted as an octal value, using the well-known (chmod(1)) way of defining access rights for owner, group and others. if construction fails, an FBB::Exception gets thrown 😭
  • SharedBuf(int id, std::ios::openmode openMode = std::ios::in | std::ios::out) — this one connects to a shared memory segment that has ID id. specifying the ios::trunc flag immediately clears the content of the shared memory, just so you know. an FBB::Exception is thrown if construction fails (e.g., no shared memory segment having ID id exists).
🚨 also copy and move constructors (and assignment operators) are not available. so don't try it, bestie, it's not giving what you think it's giving.

💅 MEMBER FUNCTIONS 💅

all members of std::streambuf and the enum values kB, MB, and GB defined by FBB::SharedEnum__ are available to you. yes, all of them. we're rich.

  • void clear() — the shared memory is first locked. next, all shared data segment are returned to the operating system, after which the shared memory segment is unlocked again. returning from clear, the FBB::SharedMemory object is effectively re-initialized, with offset and nReadable returning 0. fresh start, clean slate, main character energy ✨
  • int id() const — returns the ID of the shared memory segment. short, sweet, useful.
  • void kill() — deletes FBB::SharedBuf's shared memory, and it does this without locking the shared memory. after returning from kill the FBB::SharedBuf object is unusable. like, gone. bye 💀
  • void memInfo(std::ostream &out) — inserts info about the SharedMemory object into the provided ostream object. you get 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, its actual storage capacity, etc. the inserted information is not terminated by a final newline character, so don't come for it about the newline.
  • void remove() — the shared memory is locked, and then FBB::SharedBuf's shared memory is deleted. the FBB::SharedBuf object is unusable after returning from remove. same energy as kill but it locks first, okay? different vibes, both permanent.
  • void setMemory(SharedMemory &&tmp) — the anonymous temporary SharedMemory object passed to setMemory defines the new shared memory segment that the FBB::SharedBuf object interfaces to. you can also call it to reuse a FBB::SharedBuf object again after calling kill or remove. it's giving resurrection 🔥
  • FBB::SharedMemory &sharedMemory() — returns a reference to the FBB::SharedMemory object that the FBB::SharedBuf object interfaces to.

🧚 PROTECTED MEMBER FUNCTIONS 🧚

  • FBB::SharedCondition attachSharedCondition(std::ios::off_type offset, std::ios::seekdir origin) — returns an FBB::SharedCondition(3) object that interfaces to a shared condition variable located at offset (relative to origin) in the SharedMemory object that the SharedStreamBuf object interfaces to. an FBB::Exception is thrown if the FBB::SharedCondition object could not be constructed 😭
  • FBB::SharedCondition createSharedCondition() — returns an FBB::SharedCondition(3) object that interfaces to a newly created shared condition variable, created at the current offset of the SharedMemory object that the SharedStream object interfaces to (or at the first offset of the next physical shared memory data block, cf. sharedcondition(3bobcat)). an FBB::Exception is thrown if the FBB::SharedCondition object could not be constructed.
  • void setOpenMode(std::ios::openmode flag) — changes the streambuf's openmode to the settings defined by flag. this member gets used by, e.g., SharedStream::open, to adapt FBB::SharedBuf's openmode to the flags that are passed to open.
  • FBB::SharedMemory &sharedMemory() — returns a reference to the FBB::SharedMemory object that the SharedBuf object interfaces to.

🍓 EXAMPLE 🍓

go look at the sharedstream(3bobcat) man page, bestie, it's all there for you 🫶

🌸 FILES 🌸

bobcat/sharedbuf — 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), sharedsegment(3bobcat), sharedstream(3bobcat)

💀 BUGS 💀

okay this one actually matters so listen up. by default, exceptions thrown from within a std::stream object get caught by the stream object itself, and it sets its ios::failbit flag. so if you want exceptions to actually leave a stream object, you gotta call its exceptions member, like this:

myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);

learn it, love it, because otherwise your exception is just... sitting in there. trapped. 🙈

🔥 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'. yes, really. iconic naming, honestly.

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).

aaaand that's the whole page!! 🎀 this was libbobcat-dev_6.07.01, dated 2005-2025, and it's your girl FBB::SharedBuf(3bobcat) signing off — go write some shared memory, you absolute legend 👑✨

📦 where this page comes from