FBB::MemoryBridge(3bobcat)

📦
version 6.15.01 · 2 versions
, in ubuntu stonking

💖 FBB::MemoryBridge — Memory Segments Data Structure 💖

okay bestie, welcome to the 3bobcat manual, Memory Segments edition ✨ this one's all about FBB::MemoryBridge, and ngl it's giving main character energy for the whole Bobcat memory situation 🫶

🌸 SYNOPSIS 🌸

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

✨ DESCRIPTION ✨

so, the class FBB::MemoryBridge is literally the interface to the memory segments that Bobcat's Memory... classes use 💅 it reaches in and reads or modifies those segments through FBB::MemoryAccess wrapper class objects. and here's the tea: FBB::MemoryAccess objects are normally not directly defined by user programs — they only get made by FBB::MemoryBridge objects, which control all the read and write operations to the shared memory blocks 👑

now, multiple programs running in parallel can access the same shared memory, and lowkey that's a whole situation because FBB::MemoryBridge objects do not offer mutex facilities to stop those programs from accessing info while it's being modified 😭 such mutex facilities could be made available using flock(2) though, so iykyk.

🎀 NAMESPACE 🎀

FBB

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

🦋 INHERITS FROM 🦋

-

💅 CONSTRUCTORS 💅

  • MemoryBridge() — the default constructor defines a stub MemoryBridge object that can't immediately be used to access memory segments. but don't worry bestie, the class's move-assignment operator can turn it into a usable object 🫶
  • MemoryBridge(std::string const &bufSize, bool erase, size_t access = 0600) — constructs a MemoryBridge object. its default capacity is specified by bufSize (cf. section BUFSIZE), using memory segments containing the stream's bytes.

the access rights of the data stored in MemoryStream objects are defined by the access parameter, interpreted as an octal value, using the specifications used by (chmod(1)).

the erase parameter specifies what happens to the memory segments once the MemoryBridge object goes out of scope. when specified as false, the allocated memory segments are not destroyed when the object goes out of scope (and can be reaccessed until the computer is rebooted) using the memory object's ID (see the next constructor). when specified as true, the memory segments are erased from memory when the object goes out of scope.

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

  • MemoryBridge(int id, bool erase) — this constructor connects to a memory segment having ID id.

the erase parameter is used exactly as it is used by the previous constructor.

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

the move constructor and move-assignment operator are available, the copy constructor and copy-assignment operator are not available. no copies bestie, we don't do that here 🙈

⭐ BUFSIZE ⭐

the bufSize parameter required by the second MemoryStream constructor and the open member (see below) specifies the default number of shared memory 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 the default number of blocks is specified. e.g., "100M". internally the number of kiloBytes is converted to `pages', using the system's page size, which is commonly equal to 4 kB (so when specifying "5k" then 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 specifying 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're allocated once information is written into their areas. lazy allocation, she's efficient 💅

🌈 MEMBER FUNCTIONS 🌈

most of the following members throw exceptions when called from a MemoryBridge object that was initialized by its default constructor. you've been warned bestie 🫶

  • char *beginPtr() const — returns a pointer to the first byte of the memory block (cf. memoryblock(3bobcat)) corresponding to the current offset (cf. member offset(), below).
  • std::streamsize blockBegin() const — returns the offset of the first byte of the memory block corresponding to the current offset.
  • std::streamsize blockEnd() const — returns the offset just beyond the last byte of the memory block corresponding to the current offset.
  • std::streamsize blockSize() const — returns the size of the used memory blocks.
  • std::streamsize bufLimits() — computes the values returned by blockBegin and blockEnd corresponding to the current offset.
  • char *endPtr() const — returns a pointer to the memory block's byte corresponding to offset blockEnd().
  • char *endReadPtr() const — returns a pointer to the position in the current memory block corresponding to the last written byte in that block.
  • void extend() — extends the amount of memory blocks so that the current offset is located in a memory block that's available when bytes are written into that block.
  • int id() const — the ID of the memory block (cf. MemoryAccess(3bobcat)) controlling access to the memory data blocks is returned.
  • void info(std::ostream &out) — information about the MemoryBridge 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 giving full transparency 💖
  • void load() — loads (makes available) the memory block corresponding to the current offset.
  • std::streamsize maxEnd() const — returns the offset position corresponding to blockEnd of the current last available memory block. the value returned by this member can be updated to a larger value after calling extend().
  • std::streamsize offset() const — returns the current absolute offset position.
  • void offset(std::streamsize pos) const — sets the current absolute offset position to pos.
  • char *offsetPtr() const — returns a pointer to the byte of the memory block corresponding to the current offset.
  • size_t read(char *dest, std::streamsize len) — copies at most len bytes from the MemoryBridge's data to dest, returning the actual number of copied bytes. reading always stops when reaching the value returned by writtenUntil() (see below).
  • void setErase(bool erase) — this member is used to change the erase setting of a MemoryBridge object. it can be used by, e.g., forking programs where the program constructs a MemoryBridge object specifying erase == false, but whose memory segments should be erased when the parent process ends but not also when the child process ends. this is accomplished by calling setErase(true) in the parent process. parent privilege, iconic 👑
  • std::streamsize showmanyc() const — returns the number of characters that can be read from the current offset to the offset returned by writtenUntil().
  • void swap(MemoryBridge &other) — the information of the current MemoryBridge object is swapped with the information of the other object.
  • bool truncate(std::streamsize offset) — this member reduces or enlarges the available memory size of a MemoryBridge object 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.
  • size_t write(char *src, std::streamsize len) — copies len bytes from src to the MemoryBridge's data, starting at offset, returning the actual number of copied bytes. unless there's no more physical memory available writing succeeds. if the physical memory is exhausted an exception is thrown 😭
  • std::streamsize writtenUntil() const — returns the highest offset of the byte that was ever written to the MemoryBridge.
  • void writtenUntil(std::streamsize offset) const — updates the value returned by writtenUntil() to offset if offset is larger than that value.

🧚 EXAMPLE 🧚

see the memorystream(3bobcat) man page. go read it bestie, it's cute ✨

🍓 FILES 🍓

  • bobcat/memorybridge — defines the class interface

💜 SEE ALSO 💜

bobcat(7), chmod(1), flock(2), memoryaccess(3bobcat), memorybuf(3bobcat), memoryreadme(7bobcat), memorystream(3bobcat),

💀 BUGS 💀

None Reported. (slay, honestly)

👑 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'.

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

🌸 AUTHOR 🌸

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

and that's the whole vibe bestie, no cap 💅 this page is from libbobcat-dev_6.15.01, dated 2005-2026, and it's the FBB::MemoryBridge(3bobcat) manual — go forth and bridge those memory segments, you absolute icon 👑✨🦋

📦 where this page comes from