Struct cmb_priorityqueue

Struct Documentation

struct cmb_priorityqueue

A fixed-capacity priority 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. Objects will be retrieved in priority order.

Public Functions

struct cmb_priorityqueue *cmb_priorityqueue_create(void)

Allocate memory for a cmb_priorityqueue object.

void cmb_priorityqueue_initialize(struct cmb_priorityqueue *pqp, const char *name, uint64_t capacity)

Make an allocated cmb_priorityqueue ready for use.

Parameters:

  • pqp – Pointer to a cmb_priorityqueue

  • name – The identifying name string

  • capacity – Its maximum size, possibly CMB_UNLIMITED

void cmb_priorityqueue_terminate(struct cmb_priorityqueue *pqp)

Un-initializes an object queue.

Parameters:
void cmb_priorityqueue_destroy(struct cmb_priorityqueue *pqp)

Deallocate memory for an object queue.

Parameters:
int64_t cmb_priorityqueue_get(struct cmb_priorityqueue *pqp, 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:

  • pqp – 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_priorityqueue_put(struct cmb_priorityqueue *pqp, void *object, int64_t priority, uint64_t *handleloc)

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:

  • pqp – Pointer to an object queue

  • object – Pointer to the object

  • priority – The object priority, higher goes before lower

  • handleloc – Pointer to where to store the object queue handle. If NULL, the handle is not saved.

Returns:

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

uint64_t cmb_priorityqueue_position(struct cmb_priorityqueue *pqp, uint64_t handle)

Return the 1-based position of an object in the queue by priority order.

Parameters:

  • pqp – Pointer to an object queue

  • handle – The handle of the object to locate

Returns:

1-based position in the queue, or 0 if not found

void cmb_priorityqueue_recording_start(struct cmb_priorityqueue *pqp)

Turn on data recording.

Parameters:

  • pqp – Pointer to a object queue

void cmb_priorityqueue_recording_stop(struct cmb_priorityqueue *pqp)

Turn off data recording.

Parameters:

  • pqp – Pointer to an object queue

struct cmb_timeseries *cmb_priorityqueue_history(struct cmb_priorityqueue *pqp)

Get the recorded timeseries of queue lengths.

Parameters:

  • pqp – Pointer to an object queue

Returns:

Pointer to a cmb_timeseries containing the queue length history.

void cmb_priorityqueue_report_print(struct cmb_priorityqueue *pqp, 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:

  • pqp – 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 cmi_hashheap queue

The actual priority queue

uint64_t capacity

The maximum size, possibly CMB_UNLIMITED

bool is_recording

Is it recording its history?

struct cmb_timeseries history

History of queue lengths

Public Static Functions

static inline bool cmb_priorityqueue_cancel(struct cmb_priorityqueue *pqp, const uint64_t handle)

Cancel an object in the queue.

Parameters:

  • pqp – Pointer to an object queue

  • handle – Handle of the object to reprioritize

Returns:

true if found, false if not

static inline void cmb_priorityqueue_reprioritize(struct cmb_priorityqueue *pqp, const uint64_t handle, const int64_t priority)

Change the priority of an object in the queue, reshuffling as needed.

Parameters:

  • pqp – Pointer to an object queue

  • handle – Handle of the object to reprioritize

  • priority – New priority for the object

static inline const char *cmb_priorityqueue_name(struct cmb_priorityqueue *pqp)

Returns name of queue as const char *.

Parameters:

  • pqp – Pointer to an object queue

Returns:

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

static inline uint64_t cmb_priorityqueue_length(struct cmb_priorityqueue *pqp)

Returns current object queue length.

Parameters:

  • pqp – Pointer to an object queue

Returns:

The current queue length

static inline uint64_t cmb_priorityqueue_space(struct cmb_priorityqueue *pqp)

Returns current free space in object queue.

Parameters:

  • pqp – Pointer to an object queue

Returns:

The available space in the queue