Struct cmb_buffer

Struct Documentation

struct cmb_buffer

A two-headed fixed-capacity resource where one or more producer (putter) processes can put an amount into the one end, and one or more consumer (getter) processes can get an amount out of the other end. If enough space is not available, the producers wait, and if there is not enough content, the consumers wait.

A cmb_buffer has two resource guards, one for get (front) and one for put (rear) operations. It has a fixed capacity, of which some amount may be in use, leaving some free space (the difference between capacity and level).

Note the object-oriented structure here: The cmb_buffer class inherits the methods and properties from its (virtual) base class cmb_resourcebase. In incorporates (by composition) its two cmb_resourceguard members. These are full members of the buffer object, not pointers to some other objects. Allocating memory for a cmb_buffer object simultaneously allocates memory for the cmb_resourcebase and the two cmb_resourceguards. The details of these are encapsulated in the respective classes.

If you need a derived class from the cmb_buffer, you can declare a struct, say my_special_buffer, with a cmb_buffer as its first member followed by whatever additions you need. You can then freely cast pointers between struct my_special_buffer and struct cmb_buffer to refer to the same object as needed, as we do here.

Public Functions

struct cmb_buffer *cmb_buffer_create(void)

Allocate memory for a buffer object.

void cmb_buffer_initialize(struct cmb_buffer *bp, const char *name, uint64_t capacity)

Make an allocated buffer object ready for use.

Parameters:

  • bp – Pointer to the already allocated buffer object.

  • name – A null-terminated string naming the buffer resource.

  • capacity – The capacity of the buffer. Use UINT64_MAX for buffers of unlimited capacity.

void cmb_buffer_terminate(struct cmb_buffer *bp)

Un-initializes a buffer object.

Parameters:

  • bp – Pointer to the buffer object.

void cmb_buffer_destroy(struct cmb_buffer *bp)

Deallocates memory for a buffer object.

Parameters:

  • bp – Pointer to the buffer object.

int64_t cmb_buffer_get(struct cmb_buffer *bp, uint64_t *amntp)

Request and if necessary, wait for an amount of the buffer resource. The requested amount can be larger than the buffer space. If so, the calling process will accumulate until satisfied.

Note that the argument is a pointer to where the amount is stored. The return value CMB_PROCESS_SUCCESS (0) indicates that all went well and the value *amount equals the requested amount.

If the call was interrupted for some reason, it will be partially fulfilled, and *amntp will be the quantity remaining when interrupted. The return value is then the interrupt signal received, some other value than CMB_PROCESS_SUCCESS, possibly an application-defined reason code.

Parameters:

  • bp – Pointer to the buffer object.

  • amntp – Pointer to a variable containing the amount to be obtained. Will contain the amount actually obtained after the call.

Returns:

CMB_PROCESS_SUCCESS (0) for success, some other value otherwise.

int64_t cmb_buffer_put(struct cmb_buffer *bp, uint64_t *amntp)

Put an amount of the resource into the buffer. Wait for free space if necessary. The amount can be larger than the buffer space.

Note that the argument is a pointer to where the amount is stored. The return value CMB_PROCESS_SUCCESS (0) indicates that all went well and the value *amntp now equals zero.

If the call was interrupted for some reason, it will be partially fulfilled, and *amntp will be the quantity obtained before it was interrupted. The return value is then the interrupt signal received, some other value than CMB_PROCESS_SUCCESS, possibly an application-defined reason code.

Parameters:

  • bp – Pointer to the buffer object.

  • amntp – Pointer to a variable containing the amount to be obtained. Will contain the amount actually obtained after the call.

Returns:

CMB_PROCESS_SUCCESS (0) for success, some other value otherwise.

void cmb_buffer_recording_start(struct cmb_buffer *bp)

Turn on data recording.

Parameters:

  • bp – Pointer to the buffer object.

void cmb_buffer_recording_stop(struct cmb_buffer *bp)

Turn off data recording.

Parameters:

  • bp – Pointer to the buffer object.

struct cmb_timeseries *cmb_buffer_history(struct cmb_buffer *bp)

Get the recorded timeseries of buffer levels.

Parameters:

  • bp – Pointer to the buffer object.

Returns:

Pointer to a cmb_timeseriescontaining the buffer level history.

void cmb_buffer_print_report(struct cmb_buffer *bp, FILE *fp)

Print a simple text mode report of the buffer levels, including key statical metrics and a histogram. Mostly intended for debugging purposes, not presentation graphics.

Parameters:

  • bp – Pointer to the buffer object.

  • fp – File pointer, possibly stdout.

Public Members

struct cmi_resourcebase core

The virtual base class

struct cmb_resourceguard front_guard

Front waiting room for getters

struct cmb_resourceguard rear_guard

Rear waiting room for putters

uint64_t capacity

The buffer size, possibly UINT64_MAX for unlimited

uint64_t level

The current level in the buffer

bool is_recording

Is the buffer recording its history?

struct cmb_timeseries history

The buffer level history

Public Static Functions

static inline const char *cmb_buffer_get_name(struct cmb_buffer *bp)

Returns the name of the buffer as const char *.

Parameters:

  • bp – Pointer to the buffer object.

Returns:

A null-terminated string containing the name of the buffer.

static inline uint64_t cmb_buffer_level(struct cmb_buffer *bp)

Returns current level in buffer.

Parameters:

  • bp – Pointer to a buffer

Returns:

The current buffer level

static inline uint64_t cmb_buffer_space(struct cmb_buffer *bp)

Returns current free space in the buffer.

Parameters:

  • bp – Pointer to a buffer

Returns:

The available space in the buffer