Struct cmb_process

Defined in File cmb_process.h

Struct Documentation

struct cmb_process

The process struct, inheriting all properties from cmi_coroutine by composition, adding the name, priority, and lists of resources it may be holding and things it may be waiting for.

Public Functions

struct cmb_process *cmb_process_create(void)

Allocate memory for the process object.

Separated from initialization to enable object-oriented inheritance by composition, where any derived “classes” from cmb_process can repeat the same pattern as is done here with parent class cmi_coroutine and derived class cmb_process.

Returns:: Pointer to the newly created process.

void cmb_process_initialize(struct cmb_process *pp, const char *name, cmb_process_func procfunc, void *context, int64_t priority)

Initialize process parameters and allocates memory for the underlying coroutine stack. Uses a default stack size per process, #defined here. Does not start the process yet.

Parameters:

pp – Pointer to an already created process.
name – Null terminated string for the process name.
procfunc – The process function that will be executed when the process starts.
context – The second argument to the process function, after the pointer to the process itself.
priority – The initial priority for the process, used in various priority queues the process may find itself in.

void cmb_process_terminate(struct cmb_process *pp)

Deallocate memory for the underlying coroutine stack but not for the process object itself. In particular, the process exit value is still there.

The process must be finished (exited, stopped, returned) before getting here. Do not confuse this object destructor function with cmb_process_stop to force a running process to exit non-voluntarily. Call that first.

Parameters:

pp – Pointer to an already created process.

void cmb_process_destroy(struct cmb_process *pp)

Deallocate memory for the process struct. Call cmb_process_terminate first to ensure the coroutine stack is deallocated.

Parameters:

pp – Pointer to an already created process.

void cmb_process_start(struct cmb_process *pp)

Schedule the process to start execution at the current simulation time.

This is a non-blocking call, allowing the calling process to continue execution until it explicitly yields to some other process.

Parameters:

pp – Pointer to an already created process.

void cmb_process_resume(struct cmb_process *pp, int64_t sig)

Schedule a wakeup event at the current time for a yielded process. The processes are asymmetric coroutines and only the dispatcher can call cmi_coroutine_resume(). Hence, an event to make the dispatcher do that.

Parameters:

pp – Pointer to the target process.
sig – The signal to be passed to the target process.

void cmb_process_timers_clear(struct cmb_process *pp)

Clear all timers set for this process.

Parameters:

pp – Pointer to a cmb_process, usually the calling process itself.

uint64_t cmb_process_timer_add(struct cmb_process *pp, double dur, int64_t sig)

Set an additional timer to resume ourselves with signal sig in time dur. Does not clear any previous timers set for this process.

Parameters:

pp – Pointer to a cmb_process, usually the calling process itself.
dur – The duration to hold for, relative to the current simulation time.
sig – The signal to be passed at wakeup, e.g., CMB_PROCESS_TIMEOUT, or something user-application defined.

Returns:

The handle of the scheduled timeout event

bool cmb_process_timer_cancel(struct cmb_process *pp, uint64_t handle)

Cancel a specific timer set for this process.

Parameters:

pp – Pointer to a cmb_process, usually the calling process itself.
handle – The handle of a previously scheduled timeout.

Returns:

True if the timer is found, false if not.

int64_t cmb_process_hold(double dur)

Hold (sleep) for a specified duration of simulated time. Called from within a process.

Parameters:

dur – The duration to hold for, relative to the current simulation time.

Returns:

CMB_PROCESS_SUCCESS if returning normally at the scheduled time, otherwise some other signal value indicating the type of interruption.

int64_t cmb_process_wait_process(struct cmb_process *awaited)

Wait for some other process to finish. Called from within a process.

Returns immediately if the awaited process already is finished.

Parameters:

awaited – The process we will be waiting for.

Returns:

CMB_PROCESS_SUCCESS if the awaited process exited normally, CMB_PROCESS_STOPPED if it was stopped by some other process, something else if we were interrupted with some other signal.

int64_t cmb_process_wait_event(uint64_t ev_handle)

Wait for an event to occur. Called from within a process.

Parameters:

ev_handle – The handle of the event we will be waiting for. Note that this is not a pointer, see cmb_event.hfor details.

Returns:

CMB_PROCESS_SUCCESS if the awaited event occurred, CMB_PROCESS_CANCELLED if the event was canceled for some reason, something else if we were interrupted with some other signal.

void cmb_process_exit(void *retval)

Terminate the process with the given exit value. Called from within the process.

Parameters:

retval – The return value from the process, user defined meaning. Will be stored as the cmb_coroutine exit_value.

void cmb_process_interrupt(struct cmb_process *pp, int64_t sig, int64_t pri)

Interrupt a holding process, passing the non-zero signal value sig, which will appear as return value from whatever the target process was doing when it was interrupted. Clears all timers set for the process.

The signal cannot be CMB_PROCESS_SUCCESS, since that would appear as a normal, non-interrupted return.

Does not directly transfer control to the target, but enters an interrupt event with priority pri at the current simulation time. This lets the calling process complete whatever else it is doing at the current time before the interrupt is executed and control is transferred to the target.

Parameters:

pp – Pointer to the target process.
sig – The signal to be passed to the victim process, e.g., CMB_PROCESS_INTERRUPTED, or something user-application defined.
pri – The priority for the interrupt event that will be scheduled.

int64_t cmb_process_stop(struct cmb_process *tgt, void *retval)

Kill the target process.

Sets the target process exit value to the argument value retval. The meaning of return values for an externally terminated process is application defined. Drops any resources held by the target process. Does not transfer control to the target process.

Does not destroy the target’s memory allocation. The target process can be restarted from the beginning by calling cmb_process_start(tgt) again.

Parameters:

tgt – Pointer to the target process, different from the current (calling) process.
retval – The return value from the process. User defined meaning, often NULL for an externally killed process. Will be stored as the cmb_coroutine exit_value.

Returns:

CMB_PROCESS_SUCCESS (0) for successful stop, non-zero otherwise.

void cmb_process_name_set(struct cmb_process *pp, const char *name)

Set a new name for the process.

The name is held in a fixed size buffer of size CMB_PROCESS_NAMEBUF_SZ. Overwriting the buffer size is an error and will fire an assert.

Parameters:

pp – Pointer to a process.
name – The new name to set.

void cmb_process_priority_set(struct cmb_process *pp, int64_t pri)

Change the priority for the process.

Parameters:

pp – Pointer to a process.
pri – The new priority value.

void *cmb_process_exit_value(const struct cmb_process *pp)

Get the stored exit value from the process, as set by cmb_process_exit, cmb_process_stop, or simply returned by the process function. Will issue a warning and return NULL if the process has not yet finished.

Parameters:

pp – Pointer to a process.

Public Members

struct cmi_coroutine core: The parent coroutine

int64_t priority: The current process priority

struct cmi_slist_head awaits: What this process is waiting for, if anything

struct cmi_slist_head resources: Any resources held by this process

struct cmi_slist_head waiters: Any other processes waiting for this process to finish

char name[CMB_PROCESS_NAMEBUF_SZ]: The process name string

Public Static Functions

static inline struct cmb_process *cmb_process_current(void)

Return a pointer to the currently executing process, i.e., the calling process itself.

Returns:: Pointer to the currently executing process, NULL if called from outside a named process, such as the main process that executes the event dispatcher.

static inline int64_t cmb_process_yield(void)

Unconditionally yield control with no fixed duration or condition.

Returns:: Whatever signal value is passed by whatever process causing this one to resume again, possibly itself by setting a timer before calling.

static inline uint64_t cmb_process_timer_set(struct cmb_process *pp, const double dur, const int64_t sig)

Set a timer to resume a process with signal sig in time dur. Clears any previous timers set for this process.

Parameters:

pp – Pointer to a cmb_process, usually the calling process itself.
dur – The duration to hold for, relative to the current simulation time.
sig – The signal to be passed at wakeup, e.g., CMB_PROCESS_TIMEOUT, or something user-application defined.

Returns:

The handle of the scheduled timeout event

static inline int64_t cmb_process_kill(struct cmb_process *tgt, void *retval)

Kill the target process, syntactic alias for cmb_process_stop().

Sets the target process exit value to the argument value retval. The meaning of return values for an externally terminated process is application defined. Drops any resources held by the target process. Does not transfer control to the target process.

Does not destroy the target’s memory allocation. The target process can be restarted from the beginning by calling cmb_process_start(tgt) again.

Parameters:

tgt – Pointer to the target process, different from the current (calling) process.
retval – The return value from the process, user defined meaning, often NULL for an externally killed process. Will be stored as the cmb_coroutine exit_value.

Returns:

CMB_PROCESS_SUCCESS (0) for successful stop, non-zero otherwise.

static inline const char *cmb_process_name(const struct cmb_process *pp)

Return the process name as a const char *, since it is kept in a fixed size buffer and should not be changed directly.

If the name for some reason needs to be changed, use cmb_process_name_set to do it safely, not by modifying through this pointer.

Parameters:

pp – Pointer to a process.

static inline void *cmb_process_context(const struct cmb_process *pp)

Return a pointer to the context. Not const, the caller may change the content of the context data through this pointer.

Parameters:

pp – Pointer to a process.

Returns:

Pointer to the process context.

static inline int64_t cmb_process_priority(const struct cmb_process *pp)

Get the current priority for the process.

Parameters:

pp – Pointer to a process.

Returns:

The current priority value.

static inline enum cmb_process_state cmb_process_status(const struct cmb_process *pp)

Get the current status of the process.

Parameters:

pp – Pointer to a process.

Returns:

The current state of the process and its underlying coroutine.

enum cmb_process_state

The states a process can be in (direct from the underlying coroutine)

Values:

void *() cmb_process_func (struct cmb_process *cp, void *context): The generic process function prototype, a function taking two arguments, a pointer to a cmb_process (itself) and a pointer to some application-defined context, returning a pointer to void. This is the same as the coroutine function, except for the type of the first argument.

CMB_PROCESS_NAMEBUF_SZ: Maximum length of a process name, anything longer will be truncated.

CMB_PROCESS_SUCCESS: Return code from various process context switching calls, indicating a successful return from whatever it was calling.

CMB_PROCESS_PREEMPTED: Return code from various process context switching calls, indicating that the process was preempted by a higher priority process.

CMB_PROCESS_INTERRUPTED: Return code from various process context switching calls, indicating that the process was interrupted with this signal. (It may also bw interrupted with some other application defined signal, any 64-bit signed integer value except these predefined values.)

CMB_PROCESS_STOPPED: Return code from various process context switching calls, indicating that the process it was waiting for was stopped (killed) by some other process.

CMB_PROCESS_CANCELLED: Return code from various process context switching calls, indicating that the process request for some type of resource was canceled.

CMB_PROCESS_TIMEOUT: Return code from various process context switching calls, indicating that the process request for some type of resource was interrupted by a pre-set timer event. The timer could set any other value, this is just a preconfigured possible choice.