Struct cmb_resource

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. Ensure that no processes are waiting for the resource before terminating it.

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

struct cmi_memregistry_item destroy

Internal use

Public Static Functions

static inline CMB_MAYBE_UNUSED 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 CMB_MAYBE_UNUSED 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 CMB_MAYBE_UNUSED 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 CMB_MAYBE_UNUSED uint64_t cmb_resource_held (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.

static inline CMB_MAYBE_UNUSED struct cmb_resourceguard * cmb_resource_guard (struct cmb_resource *rp)

Return a pointer to the resource’s guard, e.g., for registering observers.

Parameters:

  • rp – Pointer to a resource.

Returns:

Pointer to the resource guard.