FBB::MemoryAccess(3bobcat)

📦
version 6.15.01 · 2 versions
, in ubuntu stonking

🌸 NAME 🌸

FBB::MemoryAccess — shared memory data structure. that's the whole vibe, bestie 💖

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

okay so the class FBB::MemoryAccess manages the access to the shared memory data blocks used by Bobcat's Memory... classes. It is not normally used directly. Instead, it's a support class used by FBB::MemoryBridge. she's the backstage crew, not the main character — but nothing on stage works without her, no cap 🫶

💜 NAMESPACE 💜

FBB

every constructor, member, operator and manipulator mentioned in this man-page is defined in the namespace FBB. all of them. not one straggler 🌈

INHERITS FROM

-

yes bestie, that dash means nothing. she's self-made 💅

🎀 CONSTRUCTORS 🎀

there are no publicly available constructors. The static member create (peep below 👇) returns a pointer to a MemoryAccess object.

copy and move constructors and assignment operators are also not available. no cloning, no yeeting, no copy-paste energy.

Note: the MemoryAccess destructor performs no actions. See also the static member create below.

MEMBER FUNCTIONS

  • 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).
  • size_t blockBegin() const — returns the offset of the first byte of the memory block corresponding to the current offset.
  • size_t blockEnd() const — returns the offset just beyond the last byte of the memory block corresponding to the current offset.
  • size_t bufLimits(size_t offset) — computes the values returned by blockBegin and blockEnd corresponding to the absolute offset position offset.
  • char *endPtr() const — returns a pointer to the memory block's byte corresponding to offset blockEnd().
  • char *endReadPtr(size_t offset) const — returns a pointer to the position in the current memory block corresponding to the absolute offset position offset.
  • int id() const — the ID of the memory block (cf. MemoryAccess(3bobcat)) controlling access to the memory data blocks is returned. like a little name tag but for shared memory 🏷️
  • void info(std::ostream &out) — information about the MemoryAccess 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 shared memory, and its actual storage capacity. it's giving full receipts 💅
  • void load() — loads (makes available) the memory block corresponding to the current offset.
  • size_t maxEnd() const — returns the absolute 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().
  • char *offsetPtr(size_t offset) — returns a pointer to the byte of the memory block corresponding to the absolute offset position offset.
  • size_t read(char *dest, size_t len, size_t offset) — copies at most len bytes from absolute offset position offset of the MemoryAccess's data to dest, returning the actual number of copied bytes. Reading always stops when reaching the value returned by writtenUntil() (see below).
  • bool truncate(std::streamsize offset) — this member reduces or enlarges the available memory size of a MemoryAccess object to size. If it's reduced then the shared memory's data bytes from size to its original size are set to 0: newly allocated shared memory areas are always initialized to 0 byte values. zeroes on arrival, every time ✨
  • size_t write(char *src, std::streamsize len, size_t offset) — copies len bytes from src to the MemoryAccess's data, starting at the absolute offset position 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. so yeah, watch out for that one.
  • size_t writtenUntil() const — returns the highest offset of the byte that was ever written to the MemoryAccess. the furthest she's ever been, literally.
  • void writtenUntil(size_t offset) const — updates the value returned by writtenUntil() to offset if offset is larger than that value.

🌟 STATIC MEMBER FUNCTIONS 🌟

  • MemoryAccess *create(std::string const &bufSize, size_t access) — returns a pointer to a newly created MemoryAccess object, defined in the computer's shared memory.
Note: the MemoryAccess destructor performs no actions. To erase the MemoryAccess object made available by create the static member drop (described next) should be used. do not just let it die on its own bestie 😭

Its default capacity is specified by bufSize (cf. section BUFSIZE).

An FBB::Exception is thrown if the shared memory data segment could not be created.

  • void drop(MemoryAccess *ptr, bool erase) — the currently attached shared memory data block and the MemoryAccess shared block are detached. If erase is true then all available shared memory blocks and the shared memory block containing the MemoryAccess pointed to by ptr are destroyed. This member is used by MemoryBridge's destructor to disconnect its MemoryAccess object. The MemoryAccess destructor performs no actions. the real cleanup queen 🧹
  • MemoryAccess *extend(size_t offset, MemoryAccess *ptr) — returns a newly allocated MemoryAccess object managing shared data blocks until at least the absolute offset position offset. Following extend the information at ptr can no longer be used. The caller is responsible for destroying the MemoryAccess object pointed to by ptr. don't touch ptr afterwards, i repeat, do NOT.
  • MemoryAccess *loadID(int id) — returns a newly allocated MemoryAccess object managing the shared data blocks of the MemoryAccess object having ID id (cf. shmat(2)).

💖 BUFSIZE 💖

the bufSize parameter required by the second MemoryStream constructor and the open member (see below) 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 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, honestly iconic 🦋

🍓 EXAMPLE 🍓

See the memorystream(3bobcat) man page. that's it, go look 👀

FILES

  • bobcat/memoryaccess — defines the class interface

SEE ALSO

bobcat(7), chmod(1), memorybridge(3bobcat), memorybuf(3bobcat), memorystream(3bobcat), shmat(2)

BUGS

None Reported. we love a clean record ✨

👑 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). free and open, as she should be 💜

AUTHOR

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

and that's the whole page bestie, no notes 💅 this was libbobcat-dev_6.15.01, dated 2005-2026 — shoutout to the FBB::MemoryAccess era, we stay obsessed 🎀✨

📦 where this page comes from