Struct cmb_resource

• Defined in File cmb_resource.h

Struct Documentation

struct cmb_resource

The resource struct inherits all properties from cmi_holdable by composition and adds the resource guard, a single pointer to the process holding the resource (if currently held), and a timeseries for logging its history.

Public Functions

struct cmb_resource *cmb_resource_create(void)

Allocate memory for a resource object.

Returns:

Pointer to the newly created resource.

void cmb_resource_initialize(struct cmb_resource *rp, const char *name)

Make an allocated resource object ready for use.

Parameters:

• rp – Pointer to an already allocated resource object.

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

void cmb_resource_terminate(struct cmb_resource *rp)

Un-initializes a resource object.

Parameters:

• rp – Pointer to an already allocated resource object.

void cmb_resource_destroy(struct cmb_resource *rp)

Deallocates memory for a resource object.

Parameters:

• rp – Pointer to an already allocated resource object.

int64_t cmb_resource_acquire(struct cmb_resource *rp)

Request and, if necessary, make the current process wait for the resource. Returns immediately if available.

Parameters:

• rp – Pointer to an initialized resource object.

Returns:

CMB_PROCESS_SUCCESS if all is well, otherwise the signal value received when interrupted or preempted.

void cmb_resource_release(struct cmb_resource *rp)

Release the resource.

Parameters:

• rp – Pointer to an initialized resource object.

int64_t cmb_resource_preempt(struct cmb_resource *rp)

Preempt the current holder and grab the resource if the calling process has higher priority than the current holder. Otherwise, it will politely wait for its turn.

Parameters:

• rp – Pointer to an initialized resource object.

Returns:

CMB_PROCESS_SUCCESS if all is well, otherwise the signal value received when interrupted or preempted.

void cmb_resource_start_recording(struct cmb_resource *rp)

Turn on data recording.

Parameters:

• rp – Pointer to an initialized resource object.

void cmb_resource_stop_recording(struct cmb_resource *rp)

Turn off data recording.

Parameters:

• rp – Pointer to an initialized resource object.

struct cmb_timeseries *cmb_resource_history(struct cmb_resource *rp)

Get the recorded timeseries of resource usage.

Parameters:

• rp – Pointer to an initialized resource object.

Returns:

Pointer to a cmb_timeseries containing the resource usage history.

void cmb_resource_print_report(struct cmb_resource *rp, 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:

• rp – Pointer to an initialized resource object.

• 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 cmb_process *holder

The current holder, if any

bool is_recording

Is it currently recording history?

struct cmb_timeseries history

The usage history, 1 for held, 0 for idle

Public Static Functions

static inline const char *cmb_resource_name(const struct cmb_resource *rp)

Returns the name of the resource as const char *.

Parameters:

• rp – Pointer to an initialized resource object.

Returns:

The name of the process as a null-terminated text string.

static inline uint64_t cmb_resource_in_use(const struct cmb_resource *rp)

Returns the number of resources currently in use.

Parameters:

• rp – Pointer to resource

Returns:

The number of units in use, 0 or 1

static inline uint64_t cmb_resource_available(const struct cmb_resource *rp)

Returns the number of currently available resources.

Parameters:

• rp – Pointer to resource

Returns:

The number of units not in use, 0 or 1

static inline uint64_t cmb_resource_held_by_process(const struct cmb_resource *rp, const struct cmb_process *pp)

Return the amount of this resource that is currently held by the given process, i.e., either zero or one.

Parameters:

• rp – Pointer to a resource.

• pp – Pointer to a process.

Returns:

One if the process holds the resource, zero otherwise.