Scheduled variables are special references to which instantaneous and delayed assignments may be made. More...

Discussion

Scheduled variables are special references to which instantaneous and delayed assignments may be made.

When such an assignment is made, all sensitive routines (with a lower priority, for instantaneous assignments) are woken and scheduled for execution in that instant. A scheduled assignment is also referred to as an event.

Note: This SSM runtime only supports scheduling a single outstanding assignment to a each scheduled variable. Earlier delayed assignments will be overwritten by subsequent delayed asssignments, but not by instantaneous assignments.

When the last reference to a scheduled variable is dropped, any outstanding scheduled assignments to it will be cancelled. Note, however, at that the current implementation of this is rather costly (linear in the total number of queued events at that time).

Data Structures
struct	ssm_sv
	A scheduled variable that supports scheduled updates with triggers. More...

Macros
#define	ssm_new_sv(v)

#define	ssm_to_sv(val) container_of((val).heap_ptr, ssm_sv_t, mm)
	Retrieve ssm_sv pointer pointed to by an ssm_value_t. More...

#define	ssm_deref(val) (ssm_to_sv(val)->value)
	Read the value of a scheduled variable. More...

#define	ssm_assign(var, prio, val)
	Instantaneous assignment to a scheduled variable. More...

#define	ssm_later(var, when, val)
	Delayed assignment to a scheduled variable. More...

#define	ssm_sensitize(var, trig) ssm_sv_sensitize(ssm_to_sv(var), trig)
	Sensitize a trigger to a scheduled variable. More...

#define	ssm_desensitize(trig) ssm_sv_desensitize(trig)
	Desensitize a trigger. More...

Typedefs
typedef struct ssm_sv	ssm_sv_t
	A scheduled variable that supports scheduled updates with triggers. More...

Functions
void	ssm_update (ssm_sv_t *sv)
	Perform a (delayed) update on a variable. More...

void	ssm_unschedule (ssm_sv_t *var)
	Unschedule any pending events on a variable. More...

ssm_value_t	ssm_new_sv_int (ssm_value_t val)
	Allocate an ssm_sv on the heap. More...

void	ssm_sv_assign_unsafe (ssm_sv_t *var, ssm_priority_t prio, ssm_value_t val)
	ssm_assign() without automatic reference counting. More...

void	ssm_sv_later_unsafe (ssm_sv_t *var, ssm_time_t when, ssm_value_t val)
	ssm_later() without automatic reference counting. More...

void	ssm_sv_sensitize (ssm_sv_t var, ssm_trigger_t trig)
	Sensitize a variable to a trigger. More...

void	ssm_sv_desensitize (ssm_trigger_t *trig)
	Desensitize a variable from a trigger. More...

Macro Definition Documentation

◆ ssm_new_sv

#define ssm_new_sv ( v )

Value:

(fprintf(stderr, "%s:%d:ssm_new_sv()\n", __FILE__, __LINE__), \

ssm_new_sv_int(v))

Definition at line 608 of file ssm.h.

◆ ssm_to_sv

#define ssm_to_sv ( val ) container_of((val).heap_ptr, ssm_sv_t, mm)

Retrieve ssm_sv pointer pointed to by an ssm_value_t.

Note: The behavior of using this macro on an ssm_value_t that does not point to a scheduled variable is undefined.

Parameters

val	the ssm_value_t

Returns: pointer to the ssm_sv_t

Definition at line 623 of file ssm.h.

◆ ssm_deref

#define ssm_deref ( val ) (ssm_to_sv(val)->value)

Read the value of a scheduled variable.

Note: The behavior of using this macro on an ssm_value_t that does not point to a scheduled variable is undefined.; The behavior of using the result of this macro as an l-value is undefined. To assign to a scheduled variable, use ssm_assign() or ssm_later().

Parameters

val	ssm_value_t that points to a scheduled variable.

Returns: the value that val points to.

Definition at line 636 of file ssm.h.

◆ ssm_assign

#define ssm_assign	(	var,
		prio,
		val
	)

Value:

  do {                                                                         \
    ssm_dup(val);                                                              \
    ssm_drop(ssm_deref(var));                                                  \
    ssm_sv_assign_unsafe(ssm_to_sv(var), prio, val);                           \
  } while (0)

Instantaneous assignment to a scheduled variable.

Updates the value of var in the current instant, and wakes up all sensitive processes at a lower priority than the calling routine.

ssm_assign() will ssm_drop() the previous value of var and ssm_dup() the new val. If the caller already knows whether var and val reside on the heap, they may call ssm_assign_unsafe() to forego the ssm_drop() and ssm_dup() calls, but will be responsible for reference counting themselves (i.e., calling ssm_dup_unsafe() and ssm_drop_unsafe() for heap objects).

Note: Does not overwrite a scheduled assignment.; The behavior of this macro when var does not point to a scheduled variable is undefined.

Parameters

var	pointer to the scheduled variable.
prio	priority of the calling routine.
val	the value to be assigned to var.

Definition at line 657 of file ssm.h.

◆ ssm_later

#define ssm_later	(	var,
		when,
		val
	)

Value:

  do {                                                                         \
    ssm_dup(val);                                                              \
    ssm_sv_later_unsafe(ssm_to_sv(var), when, val);                            \
  } while (0)

Delayed assignment to a scheduled variable.

Schedules a delayed assignment to var at a later time.

ssm_later() will ssm_dup() the scheduled val. If the caller already knows whether val resides on the heap, they may call ssm_later_unsafe() to forego the ssm_dup(), but will be responsible for reference counting themselves (i.e., calling ssm_dup_unsafe() for heap objects).

Overwrites any previously scheduled update, if any.

Note: The behavior of this macro when var does not point to a scheduled variable is undefined.

Parameters

var	pointer to the scheduled variable.
when	the time when the update should take place.
val	the value to be assigned to var.

Exceptions

SSM_INVALID_TIME	later is greater than ssm_now().
SSM_EXHAUSTED_EVENT_QUEUE	event queue ran out of space.

Definition at line 685 of file ssm.h.

◆ ssm_sensitize

#define ssm_sensitize	(	var,
		trig
	)	ssm_sv_sensitize(ssm_to_sv(var), trig)

Sensitize a trigger to a scheduled variable.

Macro provided for convenience.

See also: ssm_sv_sensitize().

Parameters

var	ssm_value_t pointing to a scheduled variable.
trig	trigger to be registered on var.

Definition at line 730 of file ssm.h.

◆ ssm_desensitize

#define ssm_desensitize ( trig ) ssm_sv_desensitize(trig)

Desensitize a trigger.

Macro provided for convenience.

See also: ssm_sv_desensitize().

Parameters

trig	the trigger.

Definition at line 740 of file ssm.h.

Typedef Documentation

◆ ssm_sv_t

typedef struct ssm_sv ssm_sv_t

A scheduled variable that supports scheduled updates with triggers.

Scheduled variables are heap-allocated built-in types that represent variables with reference-like semantics in SSM. These should be always allocated on the heap using ssm_new_sv().

Routines may directly assign to them in the current instant (ssm_assign()), or schedule a delayed assignment to them (ssm_later()). The last_updated time is recorded in each case, sensitive routines, i.e., triggers, are woken up.

At most one delayed assignment may be scheduled at a time, but a single update may wake any number of sensitive routines.

Invariant: later_time != SSM_NEVER iff this variable in the event queue.; for all ssm_sv_t v, v.mm.kind == SSM_SV_K.

Function Documentation

◆ ssm_update()

void ssm_update ( ssm_sv_t * sv )

Perform a (delayed) update on a variable.

Schedules all routine activation records sensitive to sv in the activation queue.

Should only be called if the variable is scheduled to be updated now.

Exposed so that platform code can perform external variable updates.

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

Parameters

sv	the variable.

Exceptions

SSM_NOT_READY sv was not scheduled to be updated now.

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

◆ ssm_unschedule()

void ssm_unschedule ( ssm_sv_t * var )

Unschedule any pending events on a variable.

Should be called before the variable is dropped.

Nothing happens if the variable does not have a pending event.

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

Parameters

var	the variable.

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

◆ ssm_new_sv_int()

ssm_value_t ssm_new_sv_int ( ssm_value_t val )

Allocate an ssm_sv on the heap.

Note: Initialization does not count as an update event; last_updated is initialized to SSM_NEVER.; The later_value field is left uninitialized.

Parameters

val	the initial value of the scheduled variable.

Returns: ssm_value_t pointing to the ssm_sv on the heap.

Definition at line 283 of file ssm-mem.c.

◆ ssm_sv_assign_unsafe()

void ssm_sv_assign_unsafe	(	ssm_sv_t *	var,
		ssm_priority_t	prio,
		ssm_value_t	val
	)

ssm_assign() without automatic reference counting.

Note: Does not overwrite a scheduled assignment.

Parameters

var	pointer to the scheduled variable.
prio	priority of the calling routine.
val	the value to be assigned to var.

See also: ssm_assign().

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

◆ ssm_sv_later_unsafe()

void ssm_sv_later_unsafe	(	ssm_sv_t *	var,
		ssm_time_t	when,
		ssm_value_t	val
	)

ssm_later() without automatic reference counting.

Overwrites any previously scheduled update, if ssm_laterr

Note: ssm_drop() will be called on the previous later_value, so the caller is not responsible for checking that.

Parameters

var	pointer to the scheduled variable.
when	the time when the update should take place.
val	the value to be assigned to var.

Exceptions

SSM_INVALID_TIME	later is greater than ssm_now().
SSM_EXHAUSTED_EVENT_QUEUE	event queue ran out of space.

See also: ssm_later().

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

◆ ssm_sv_sensitize()

void ssm_sv_sensitize	(	ssm_sv_t *	var,
		ssm_trigger_t *	trig
	)

Sensitize a variable to a trigger.

Adds a trigger to a scheduled variable, so that trig's activation record is awoken when the variable is updated.

This function should be called by a routine before sleeping (yielding).

Parameters

var	pointer to the scheduled variable.
trig	trigger to be registered on var.

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

◆ ssm_sv_desensitize()

void ssm_sv_desensitize ( ssm_trigger_t * trig )

Desensitize a variable from a trigger.

Remove a trigger from its variable.

This function should be called by a routine after returning from sleeping.

Parameters

trig	the trigger.

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

Discussion

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ ssm_new_sv

◆ ssm_to_sv

◆ ssm_deref

◆ ssm_assign

◆ ssm_later

◆ ssm_sensitize

◆ ssm_desensitize

Typedef Documentation

◆ ssm_sv_t

Function Documentation

◆ ssm_update()

◆ ssm_unschedule()

◆ ssm_new_sv_int()

◆ ssm_sv_assign_unsafe()

◆ ssm_sv_later_unsafe()

◆ ssm_sv_sensitize()

◆ ssm_sv_desensitize()