Struct cmb_resourcepool

Struct Documentation

struct cmb_resourcepool

A counting semaphore that supports acquire(), release(), and preempt() in specific amounts against a fixed resource capacity, where a process also can acquire more of a resource it already holds some amount of, or release parts of its holding. Several processes can be holding parts of the resource capacity at the same time, possibly also different amounts.

Public Functions

struct cmb_resourcepool *cmb_resourcepool_create(void)

Allocate memory for a resource pool.

Returns:

Pointer to an allocated resource pool.

void cmb_resourcepool_initialize(struct cmb_resourcepool *rpp, const char *name, uint64_t capacity)

Make an allocated resource pool ready for use.

Parameters:

  • rpp – Pointer to a resource pool.

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

  • capacity – The maximum amount that can be assigned at the same time.

void cmb_resourcepool_terminate(struct cmb_resourcepool *rpp)

Un-initializes a resource pool.

Parameters:

  • rpp – Pointer to a resource pool.

void cmb_resourcepool_destroy(struct cmb_resourcepool *rpp)

Deallocates memory for a resource pool.

Parameters:

  • rpp – Pointer to an allocated resource pool object.

uint64_t cmb_resourcepool_held_by_process(struct cmb_resourcepool *rpp, const struct cmb_process *pp)

Return the amount of this pool that is currently held by the given process, possibly zero.

Parameters:

  • rpp – Pointer to a resource pool.

  • pp – Pointer to a cmb_process

Returns:

The amount from this resource pool that is held by the process.

int64_t cmb_resourcepool_acquire(struct cmb_resourcepool *rpp, uint64_t req_amount)

Request and, if necessary, wait for an amount of the resource pool. The calling process may already hold some and try to increase its holding with this call, or to acquire its first helping.

It will either get the required req_amount and return CMB_PROCESS_SUCCESS, be preempted and return CMB_PROCESS_PREEMPTED, or be interrupted and return some other value. If it is preempted, the process lost everything it had and returns empty-handed. If interrupted by any other signal, it returns with the same req_amount as it had at the beginning of the call.

Only the signal is returned, not the req_amount obtained or held. The calling process needs to keep track of this itself based on the return signal values. In particular, do not assume that the process has received the requested req_amount when it returns.

Parameters:

  • rpp – Pointer to a resource pool.

  • req_amount – The requested amount.

Returns:

CMB_PROCESS_SUCCESS if successful, otherwise the signal received when preempted or interrupted.

int64_t cmb_resourcepool_preempt(struct cmb_resourcepool *rpp, uint64_t req_amount)

Preempt the current holders and grab the amount, starting from the lowest priority holder. If there is not enough to cover the amount before it runs into holders with equal or higher priority than the caller, it will politely wait in line for the remainder. It only preempts processes with strictly lower priority than itself, otherwise acts like cmb_resourcepool_acquire().

As for cmb_resourcepool_acquire(), it can either return with the requested req_amount, an unchanged req_amount (interrupted), or nothing at all (preempted). This function does not return the req_amount received or held, only the signal value.

Parameters:

  • rpp – Pointer to a resource pool.

  • req_amount – The requested amount.

Returns:

CMB_PROCESS_SUCCESS if successful, otherwise the signal received when preempted or interrupted.

void cmb_resourcepool_release(struct cmb_resourcepool *rpp, uint64_t rel_amount)

Release an amount of the resource back to the pool, not necessarily everything that the calling process holds, but not more than it is currently holding. Always returns immediately.

Parameters:

  • rpp – Pointer to a resource pool.

  • rel_amount – The requested amount.

void cmb_resourcepool_stop_recording(struct cmb_resourcepool *rsp)

Turn off data recording.

Parameters:

  • rsp – Pointer to a resource pool.

struct cmb_timeseries *cmb_resourcepool_get_history(struct cmb_resourcepool *rsp)

Get the recorded timeseries of resource usage.

Parameters:

  • rsp – Pointer to a resource pool.

Returns:

Pointer to a cmb_timeseries containing the usage history.

void cmb_resourcepool_print_report(struct cmb_resourcepool *rsp, FILE *fp)

Print a simple text mode report of the resource usage, including key statistical metrics and a histogram. Mostly intended for debugging purposes, not presentation graphics.

Parameters:

  • rsp – Pointer to a resource pool.

  • fp – File pointer, possibly stdout.

Public Members

struct cmi_holdable core

The virtual base class

struct cmb_resourceguard guard

The gatekeeper maintaining an orderly queue of waiting processes

struct cmi_hashheap holders

The processes currently holding some, if any

uint64_t capacity

The maximum amount that can be assigned to processes

uint64_t in_use

The amount currently in use, less than or equal to the capacity

bool is_recording

Is it currently recording history?

struct cmb_timeseries history

The usage history

Public Static Functions

static inline const char *cmb_resourcepool_get_name(struct cmb_resourcepool *rsp)

Returns name of pool as const char *.

Parameters:

  • rsp – Pointer to a resource pool.

Returns:

A null-terminated string with the name of the resource pool.

static inline uint64_t cmb_resourcepool_in_use(struct cmb_resourcepool *rsp)

Returns the number of resources currently in use.

Parameters:

  • rsp – Pointer to a resource pool

Returns:

The number of units in use

static inline uint64_t cmb_resourcepool_available(struct cmb_resourcepool *rsp)

Returns the number of currently available resources.

Parameters:

  • rsp – Pointer to a resource pool

Returns:

The number of units not in use