Activation records

The local state of each user-defined coroutine is saved within its activation record. More...

Discussion

The local state of each user-defined coroutine is saved within its activation record.

Each coroutine executes at most once per instant, and between instants, their activation records are managed by the runtime scheduler.

In addition to the arguments and local variables of a coroutine, which are specific to each coroutine, activation records also contain some common fields, such as the priority and depth of a coroutine. These common fields are found in the ssm_act_t "base class", which should be embedded in the beginning of each routine-specific activation record.

Activation records are heap-allocated and initialized in routine-specific enter function and registered with the scheduler using ssm_activate(). When ssm_tick() is called, a coroutine is executed for that instant using its step function. When a coroutine returns, its step function should call ssm_leave() to deallocate the activation record.

Data Structures
struct	ssm_act
	Activation record for an SSM routine. More...
struct	ssm_trigger
	Indicates a routine should run when a scheduled variable is written. More...

Macros
#define	SSM_ROOT_PRIORITY   0
	The priority for the entry point of an SSM program. More...
#define	SSM_ROOT_DEPTH   (sizeof(ssm_priority_t) * 8)
	The depth at the entry point of an SSM program. More...
#define	ssm_has_children(act)   ((act)->children != 0)
	Whether an activation record has any children. More...
#define	ssm_enter(si, st, pa, pr, de)

Typedefs
typedef uint32_t	ssm_priority_t
	Thread priority. More...
typedef uint8_t	ssm_depth_t
	Index of least significant bit in a group of priorities. More...
typedef void	ssm_stepf_t(struct ssm_act *)
	The function that does an instant's work for a routine. More...
typedef struct ssm_act	ssm_act_t
	Activation record for an SSM routine. More...
typedef struct ssm_trigger	ssm_trigger_t
	Indicates a routine should run when a scheduled variable is written. More...

Functions
bool	ssm_active (void)
	Whether there are still active processes in the activation queue. More...
void	ssm_tick (void)
	Run the system for the next scheduled instant. More...
ssm_act_t *	ssm_enter_int (size_t size, ssm_stepf_t step, ssm_act_t *parent, ssm_priority_t priority, ssm_depth_t depth)
	Allocate and initialize a routine activation record. More...
void	ssm_leave (ssm_act_t *act, size_t size)
	Destroy the activation record of a routine before leaving. More...
void	ssm_activate (ssm_act_t *act)
	Schedule a routine to run in the current instant. More...

Variables
ssm_act_t	ssm_top_parent
	An activation record for the parent of the top-most routine. More...

Macro Definition Documentation

SSM_ROOT_PRIORITY

#define SSM_ROOT_PRIORITY   0

The priority for the entry point of an SSM program.

Definition at line 105 of file ssm.h.

SSM_ROOT_DEPTH

#define SSM_ROOT_DEPTH   (sizeof(ssm_priority_t) * 8)

The depth at the entry point of an SSM program.

Definition at line 114 of file ssm.h.

ssm_has_children

#define ssm_has_children

(

act

)

((act)->children != 0)

Whether an activation record has any children.

Definition at line 148 of file ssm.h.

ssm_enter

#define ssm_enter	(		si,
			st,
			pa,
			pr,
			de
	)

Value:

  (fprintf(stderr, "%s:%d:ssm_enter(%lu,_,_,_,_,_)\n", __FILE__, __LINE__,     \
           (si)),                                                              \
   ssm_enter_int((si), (st), (pa), (pr), (de)))

Definition at line 179 of file ssm.h.

Typedef Documentation

ssm_priority_t

typedef uint32_t ssm_priority_t

Thread priority.

Lower numbers execute first in an instant.

Definition at line 102 of file ssm.h.

ssm_depth_t

typedef uint8_t ssm_depth_t

Index of least significant bit in a group of priorities.

This only needs to represent the number of bits in the ssm_priority_t type.

Definition at line 111 of file ssm.h.

ssm_stepf_t

typedef void ssm_stepf_t(struct ssm_act *)

The function that does an instant's work for a routine.

Definition at line 117 of file ssm.h.

ssm_act_t

typedef struct ssm_act ssm_act_t

Activation record for an SSM routine.

Routine activation record "base class." A struct for a particular routine must start with this type but then may be followed by routine-specific fields.

ssm_trigger_t

typedef struct ssm_trigger ssm_trigger_t

Indicates a routine should run when a scheduled variable is written.

Node in linked list of activation records, maintained by each scheduled variable to determine which continuations should be scheduled when the variable is updated.

Function Documentation

ssm_active()

bool ssm_active

(

void

)

Whether there are still active processes in the activation queue.

Note

Intended for platform code; should not be used in user code.

Returns

true if there is at least one active process, false otherwise.

Definition at line 271 of file ssm-scheduler.c.

ssm_tick()

void ssm_tick

(

void

)

Run the system for the next scheduled instant.

If there is nothing left to run in the current instant, advance now to the time of the earliest event in the queue, if any.

Removes every event at the head of the event queue scheduled for now, updates each variable's current value from its later value, and schedules all sensitive triggers in the activation queue. Finally, execute the step functions of all scheduled routines, in order of priority.

Should only be called if there are activation records to execute now, or if now is earlier than ssm_next_event_time().

Note

Intended for platform code; should not be used in user code.

Exceptions

SSM_INTERNAL_ERROR

there are stale events in the queue before now.

Definition at line 425 of file ssm-scheduler.c.

ssm_enter_int()

ssm_act_t* ssm_enter_int	(	size_t	size,
		ssm_stepf_t	step,
		ssm_act_t *	parent,
		ssm_priority_t	priority,
		ssm_depth_t	depth
	)

Allocate and initialize a routine activation record.

Uses the underlying memory allocator to allocate an activation record of a given size, and initializes it with the rest of the fields. Also increments the number of children that parent has.

This function assumes that the embedded ssm_act_t is at the beginning of the allocated activation record. That is, it has the following layout:

struct {
  ssm_act_t act;
  // Other fields
};

Parameters

size	the size of the routine activation record to allocate.
step	the step function of the routine.
parent	the parent (caller) of the activation record.
priority	the priority of the activation record.
depth	the depth of the activation record.

Returns

the newly initialized activation record.

Exceptions

SSM_EXHAUSTED_MEMORY

out of memory.

Definition at line 273 of file ssm-scheduler.c.

ssm_leave()

void ssm_leave	(	ssm_act_t *	act,
		size_t	size
	)

Destroy the activation record of a routine before leaving.

Calls the parent if act is the last child.

Parameters

act	the activation record of the routine to leave.
size	the size of activation record.

Definition at line 290 of file ssm-scheduler.c.

ssm_activate()

void ssm_activate

(

ssm_act_t *

act

)

Schedule a routine to run in the current instant.

This function is idempotent: it may be called multiple times on the same activation record within an instant; only the first call has any effect.

Parameters

act	activation record of the routine to schedule.

Exceptions

SSM_EXHAUSTED_ACT_QUEUE

the activation record is full.

Definition at line 298 of file ssm-scheduler.c.

Variable Documentation

ssm_top_parent

ssm_act_t ssm_top_parent

extern

An activation record for the parent of the top-most routine.

This activation record should be used as the parent of the entry point. For example, if the entry point is named main, with activation record type main_act_t and step function step_main:

ssm_enter(sizeof(main_act_t), step_main, &ssm_top_parent,
          SSM_ROOT_PRIORITY, SSM_ROOT_DEPTH)

Definition at line 9 of file ssm-top-act.c.