FBB::MemoryStream(3bobcat)

📦
version 6.15.01 · 2 versions
, in ubuntu stonking

🌸 FBB::MemoryStream — I/O operations on memory segments 🌸

okay bestie, welcome to FBB::MemoryStream(3bobcat), part 1 of 2 💖 this is the part where we meet the class, the constructors, and every single member function. no skipping, no summarizing, we're doing the whole thing 🫶

✨ NAME ✨

FBB::MemoryStream — I/O operations on memory segments. periodt 💅

✨ SYNOPSIS ✨

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

yes queen, one include and one link flag, that's the whole vibe 🌈

✨ DESCRIPTION ✨

so basically this class is giving both std::istream and std::ostream energy at the same time, but it does all its reading and writing on memory segments (like, cf. shmget(2), iykyk) ✨

and here's the tea you need to internalize: just like std::fstream objects, FBB::MemoryStream objects do not keep separate offsets for reading and writing. nope. the seek members always refer to the one single offset that the FBB::MemoryBridge object maintains — and that's the object your MemoryStream interfaces with, indirectly. one offset, one truth, no cap 💀

✨ NAMESPACE ✨

FBB

every single constructor, member, operator and manipulator mentioned in this man page lives in the namespace FBB. all of them. every last one 🎀

✨ INHERITS FROM ✨

  • FBB::MemoryBuf (private inheritance) 🙈
  • std::iostream 👑

✨ CONSTRUCTORS ✨

  • MemoryStream() — the default constructor. it defines a stub MemoryStream object that cannot immediately be used to access memory segments. to actually use it you have to call its member open first. it's like a blank canvas bestie, beautiful but currently useless 🌸
  • MemoryStream(std::string const &bufSize, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600) — constructs a MemoryStream object that inherits all the facilities of the std::iostream class. its default capacity is specified by bufSize (go peek at the BUFSIZE section for the whole story), using memory segment(s) that contain the stream's bytes.

the access rights of the data stored in MemoryStream objects are defined by the access parameter, which gets interpreted as an octal value, using the same specifications that chmod(1) uses 🔐

the erase parameter is the "what happens when you leave" setting for the memory segments once the MemoryStream object goes out of scope. when it's omitted or specified as false, the allocated memory segments are not erased from memory when the object goes out of scope — and yes, that means they can be reaccessed until the computer is rebooted, using the memory object's ID (see the next constructor 👀). when it's specified as true, the memory segments are erased from memory when the object goes out of scope. choose wisely bestie 💅

if construction fails, an FBB::Exception is thrown. 😭

  • MemoryStream(int id, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out) — constructs a MemoryStream that connects to the memory segments created by the previous constructor, using the memory segment's ID defined by that constructor. it's giving "reunited and it feels so good" 🦋

the erase parameter is used exactly the way it's used by the previous constructor. same rules, same drama.

specifying the ios::trunc flag (or a comparable flag — like, merely ios::out counts) immediately clears the current content of the memory segments. gone. poof. 💀

an FBB::Exception is thrown if construction fails (e.g., when no memory segment having ID id exists). 😭

⚠️ the move/copy constructors and assignment operators are not available. not on the menu, don't ask 🚫

✨ BUFSIZE ✨

the bufSize parameter — required by the second MemoryStream constructor and by the open member (scroll down for that one) — specifies the default number of shared memory blocks and their sizes 🌈

the size of the memory blocks is specified as k, M or G, indicating block sizes in kilo-, Mega- and GigaBytes. before those letters you specify the default number of blocks. e.g., "100M" ✨

internally the number of kiloBytes gets converted to pages, using the system's page size, which is commonly equal to 4 kB — so when you specify "5k", the stream prepares for two shared data segments, each having a capacity of 4 kB 🎀

the number of MegaBytes is used as specified, and when you specify GB the data segments are .5 GB.

the number of shared data segments is automatically enlarged when the current capacity is exceeded, and the potentially available data segments are initially not allocated: they get allocated once information is written into their areas. lazy allocation, honestly iconic 🧚

✨ MEMBER FUNCTIONS ✨

all members of std::iostream are available. yes, all of them, we're spoiled 🫶

  • void exceptions(std::ios::iostate flag) — after you call this member, exceptions thrown while processing a MemoryStream leave the MemoryStream object, setting the stream's state to flag. such exceptions are caught as usual, while the object's iostate is set to flag, which lets you distinguish internally generated exceptions from other exceptions 👑 commonly the argument std::ios::badbit is used.
  • int id() const — the ID of the memory segments is returned. that's it, that's the whole function 💅
  • void info(std::ostream &out) — information about the object's MemoryBuf is inserted into out: the IDs of the memory data blocks, their sizes, the current maximum number of memory data blocks, the number of bytes that can be read from the memory segments, and its actual storage capacity. it's the full gossip session 🌸
  • std::streamsize maxEnd() const — when using a MemoryStream object, the offset just beyond the current maximum offset is returned. e.g., if a MemoryStream object is configured with 5 data blocks of 1 MB each, then maxEnd returns 5 * 1024 * 1024. when the object extends its number of data blocks, maxEnd returns the corresponding new value 🔥
  • void open(char const *bufSize, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600) — this member can be used to activate a MemoryStream object that was initially created by its default constructor. it expects the same argument as the second constructor. a matching close member does not exist and is not required 🎀

if opening fails, an FBB::Exception is thrown. 😭

  • void open(int id, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600) — this member can be used to activate a MemoryStream object that was initially created by its default constructor, specifying the ID of a previously constructed MemoryStream object. it expects the same argument as the third constructor. a matching close member does not exist and is not required ✨

if opening fails, an FBB::Exception is thrown. 😭

  • void setErase(bool erase) — this member is used to change the erase setting of a MemoryStream object. it can be used by, e.g., forking programs where the program constructs a MemoryStream object specifying erase == false, but whose memory segments should be erased when the parent process ends and not also when the child process ends. this is accomplished by calling setErase(true) in the parent process. family drama, resolved 💅
  • void truncate(std::streamsize size) — this member is used to reduce or enlarge the available memory size of a MemoryStream to size. if it's reduced, then the memory segments' data bytes from size to its original size are set to 0. newly allocated memory segments are always initialized to 0 byte values. fresh start energy 🌈
💖 that's the first half bestie, part 2 is coming with the example, the files, the SEE ALSO and the bugs section — so don't go anywhere, we're not done yet ✨

okay so last lil' drop of links before we wrap this whole thing up 💖 — here's where the entire Bobcat situation lives:

  • https://fbb-git.gitlab.io/bobcat/: the gitlab project page, that's literally the spot bestie;
  • Debian Bobcat project files:
    • libbobcat6 — the debian package holding the shared library, the changelog and the copyright note;
    • libbobcat-dev — the debian package holding the static library, the headers, the manual pages, and all the developer info;

🐱 BOBCAT 🐱

fun fact, no cap: Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

ngl that is such a clean acronym and I'm obsessed 🫶

This is free software, distributed under the terms of the GNU General Public License (GPL). so yes bestie, it's free, it's GPL, go be great with it 💅

🫶 AUTHOR 🫶

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

and that's the whole page, bestie, we made it to the end 🎀✨ this one rides along with libbobcat-dev_6.15.01, and the timeline stamped on it runs all the way from 2005 to 2026 — a two-decade glow-up, which is honestly iconic behavior 👑💜 go stream your memory like the main character you are, periodt 🦋🌸

📦 where this page comes from