ost::Buffer(3)

📦 version 1.8.1, in ubuntu jammy

💖 ost::Buffer 💖 — Library Functions Manual

okay bestie, grab a snack and your emotional support iced coffee, because today we're unpacking ost::Buffer from GNU CommonC++ 🫶 — that's the C++ class chillin' in section 3 of the manual (library functions, iykyk). She's abstract, she's threaded, she's lowkey the backbone of inter-thread gossip. Let's go. ✨

🌸 NAME 🌸

ost::Buffer — the buffer class, and she is the moment: an IPC service built upon a buffer of fixed capacity that can be used to transfer objects between one or more producer and consumer threads. no cap. 💅

🎀 SYNOPSIS 🎀

#include <buffer.h>

Inherits ost::Conditional.

Inherited by ost::FixedBuffer.

👑 Public Member Functions

  • Buffer (size_t capacity) — create a buffer object of known capacity 💖
  • virtual ~Buffer () — in derived functions, may be used to free the actual memory used to hold buffered data
  • size_t getSize (void) — return the capacity of the buffer as specified at creation
  • size_t getUsed (void) — return the current capacity in use for the buffer
  • size_t wait (void *buf, timeout_t timeout=0) — let one or more threads wait for an object to become available in the buffer
  • size_t post (void *buf, timeout_t timeout=0) — post an object into the buffer and enable a waiting thread to receive it
  • size_t peek (void *buf) — peek at the current content (first object) in the buffer
  • virtual bool isValid (void) — new virtual to test if buffer is a valid object

⭐ Static Public Attributes

  • static const size_t timeout — value to return when a timed operation returned with a timeout

🦋 Protected Member Functions

  • virtual size_t onPeek (void *buf)=0 — invoke derived class buffer peeking method
  • virtual size_t onWait (void *buf)=0 — invoke derived class object request from buffer
  • virtual size_t onPost (void *buf)=0 — invoke derived class posting of object to buffer

(Note that these are not member functions.)

  • size_t get (Buffer &b, void *o, timeout_t t=0)
  • size_t put (Buffer &b, void *o, timeout_t t=0)
  • size_t peek (Buffer &b, void *o)

💜 Detailed Description 💜

The buffer class represents an IPC service that is built upon a buffer of fixed capacity that can be used to transfer objects between one or more producer and consumer threads. it's giving ✨message passing✨

Producer threads post objects into the buffer, and consumer threads wait for and receive objects from the buffer. Semaphores are used to block the buffer from overflowing and indicate when there is data available, and mutexes are used to protect multiple consumers and producer threads from stepping over each other. teamwork, bestie. 🫶

The buffer class is an abstract class in that the actual data being buffered is not directly specified within the buffer class itself. The buffer class should be used as a base class for a class that actually implements buffering and which may be aware of the data types actually are being buffered. A template class could be created based on buffer for this purpose. Another possibility is to create a class derived from both Thread and Buffer which can be used to implement message passing threads. 👑

Author David Sugar dyfet@ostel.com

Producer/Consumer buffer for use between threads.

🧚 Constructor & Destructor Documentation 🧚

🍓 ost::Buffer::Buffer (size_t capacity)

Create a buffer object of known capacity. iconic.

Parameters

  • capacity is the integer capacity of the buffer.

🍓 virtual ost::Buffer::~Buffer () [virtual]

In derived functions, may be used to free the actual memory used to hold buffered data. clean up after yourself, queen 💅

🔥 Member Function Documentation 🔥

💖 size_t ost::Buffer::getSize (void) [inline]

Return the capacity of the buffer as specified at creation.

Returns

  • size of buffer.

💖 size_t ost::Buffer::getUsed (void) [inline]

Return the current capacity in use for the buffer. Free space is technically getSize() - getUsed(). do with that math what you will 📐

Returns

  • integer used capacity of the buffer.

See also

  • getSize

💖 virtual bool ost::Buffer::isValid (void) [virtual]

New virtual to test if buffer is a valid object. vibe check, basically ✅

Returns

  • true if object is valid.

Reimplemented in ost::FixedBuffer.

💖 virtual size_t ost::Buffer::onPeek (void * buf) [protected], [pure virtual]

Invoke derived class buffer peeking method.

Returns

  • size of object found.

Parameters

  • buf pointer to copy contents of head of buffer to.

Implemented in ost::FixedBuffer.

💖 virtual size_t ost::Buffer::onPost (void * buf) [protected], [pure virtual]

Invoke derived class posting of object to buffer.

Returns

  • size of object posted.

Parameters

  • buf pointer to object being posted to the buffer.

Implemented in ost::FixedBuffer.

💖 virtual size_t ost::Buffer::onWait (void * buf) [protected], [pure virtual]

Invoke derived class object request from buffer.

Returns

  • size of object returned.

Parameters

  • buf pointer to hold object returned from the buffer.

Implemented in ost::FixedBuffer.

💖 size_t ost::Buffer::peek (void * buf)

Peek at the current content (first object) in the buffer. just a lil look, no touching 👀

Returns

  • size of object in the buffer.

Parameters

  • buf pointer to store object found in the buffer.

Referenced by peek().

💖 size_t ost::Buffer::post (void * buf, timeout_t timeout = 0)

Post an object into the buffer and enable a waiting thread to receive it.

Returns

  • size of object posted in bytes.

Parameters

  • buf pointer to object to store in the buffer.
  • timeout time to wait.

Referenced by put().

💖 size_t ost::Buffer::wait (void * buf, timeout_t timeout = 0)

Let one or more threads wait for an object to become available in the buffer. The waiting thread(s) will wait forever if no object is ever placed into the buffer.

⚠️ fr fr, bestie — forever means forever here. if nothing ever gets posted, those threads are just gonna sit there. not a drill. 💀

Returns

  • size of object passed by buffer in bytes.

Parameters

  • buf pointer to store object retrieved from the buffer.
  • timeout time to wait.

Referenced by get().

References wait().

Examples

  • SampleSocketPort.cpp.

References peek().

References post().

🎀 Member Data Documentation 🎀

⭐ const size_t ost::Buffer::timeout [static]

value to return when a timed operation returned with a timeout. she's the "oops, ran out of patience" flag 💅

👑 Author 👑

Generated automatically by Doxygen for GNU CommonC++ from the source code.

and that's the whole page, bestie, you ate it 🍓✨ this was GNU CommonC++, dated Sun Dec 27 2020, and she lives at ost::Buffer(3) — go forth and buffer responsibly 💖🦋🎀

📦 where this page comes from