Struct cmb_objectqueue

Struct Documentation

struct cmb_objectqueue

A fixed-capacity queue where one or more producer processes (putters) can put arbitrary objects into the one end, and one or more consumer processes (getters) can get objects out of the other end. If space is not available, the producers wait, and if there is no content, the consumers wait.

Public Functions

struct cmb_objectqueue *cmb_objectqueue_create(void)

Allocate memory for a cmb_objectqueue object.

void cmb_objectqueue_initialize(struct cmb_objectqueue *oqp, const char *name, uint64_t capacity)

Make an allocated cmb_objectqueue ready for use.

Parameters:

  • oqp – Pointer to a cmb_objectqueue

  • name – The identifying name string.

  • capacity – Its maximum size, possibly CMB_OBJECTQUEUE_UNLIMITED for unlimited.

void cmb_objectqueue_terminate(struct cmb_objectqueue *oqp)

Un-initializes an object queue.

Parameters:
void cmb_objectqueue_destroy(struct cmb_objectqueue *oqp)

Deallocate memory for an object queue.

Parameters:
int64_t cmb_objectqueue_get(struct cmb_objectqueue *oqp, void **objectloc)

Request and, if necessary, wait for an object from the queue. Only one object can be requested at a time.

Note that the object argument is a pointer to where the object is to be stored. The return value CMB_PROCESS_SUCCESS (0) indicates that all went well and that the object pointer location now contains a valid pointer to an object.

If the call was interrupted for some reason, the return value is the interrupt signal received, some value other than CMB_PROCESS_SUCCESS. The object pointer will be NULL.

Parameters:

  • oqp – Pointer to an object queue

  • objectloc – Pointer to the location for storing the obtained object.

Returns:

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

int64_t cmb_objectqueue_put(struct cmb_objectqueue *oqp, void *object)

Put an object into the queue, if necessary, waiting for free space.

If the call was interrupted for some reason, the return value is the interrupt signal received, some value other than CMB_PROCESS_SUCCESS. The object pointer will still be unchanged.

Parameters:

  • oqp – Pointer to an object queue

  • object – Pointer to the object

Returns:

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

uint64_t cmb_objectqueue_position(struct cmb_objectqueue *oqp, void *object)

Returns position of object in object queue.

Parameters:

  • oqp – Pointer to an object queue

  • object – Pointer to some object, possibly NULL

Returns:

The position of the object in the queue, zero if not found. Will return the first match (nearest to the front of the queue) if several matches.

void cmb_objectqueue_recording_start(struct cmb_objectqueue *oqp)

Turn on data recording.

Parameters:

  • oqp – Pointer to a object queue

void cmb_objectqueue_recording_stop(struct cmb_objectqueue *oqp)

Turn off data recording.

Parameters:

  • oqp – Pointer to an object queue

struct cmb_timeseries *cmb_objectqueue_history(struct cmb_objectqueue *oqp)

Get the recorded timeseries of queue lengths.

Parameters:

  • oqp – Pointer to an object queue

Returns:

Pointer to a cmb_timeseries containing the queue length history.

void cmb_objectqueue_report_print(struct cmb_objectqueue *oqp, FILE *fp)

Print a simple text mode report of the queue lengths, including key statistical metrics and histograms. Mostly intended for debugging purposes, not presentation graphics.

Parameters:

  • oqp – Pointer to an object queue

  • 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

struct queue_tag *queue_head

The head of the queue, NULL if empty

struct queue_tag *queue_end

The tail of the queue, NULL if empty

uint64_t capacity

The maximum size, possibly CMB_UNLIMITED

uint64_t length

The current queue length

bool is_recording

Is it recording its history?

struct cmb_timeseries history

History of queue lengths

Public Static Functions

static inline const char *cmb_objectqueue_name(struct cmb_objectqueue *oqp)

Returns name of queue as const char *.

Parameters:

  • oqp – Pointer to an object queue

Returns:

A null-terminated string containing the name of the object queue.

static inline uint64_t cmb_objectqueue_length(struct cmb_objectqueue *oqp)

Returns current object queue length.

Parameters:

  • oqp – Pointer to an object queue

Returns:

The current queue length

static inline uint64_t cmb_objectqueue_space(struct cmb_objectqueue *oqp)

Returns current free space in object queue.

Parameters:

  • oqp – Pointer to an object queue

Returns:

The available space in the queue