ssm.h File Reference
Interface to the SSM runtime. More...
#include <stdbool.h>#include <stddef.h>#include <stdint.h>#include <stdio.h>
Include dependency graph for ssm.h:
This graph shows which files directly or indirectly include this file:
Go to the source code of this file.
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... | |
| union | ssm_value_t |
| SSM values are either "packed" values or heap-allocated. More... | |
| struct | ssm_mm |
| The memory management metadata "header" for heap-allocated objects. More... | |
| struct | ssm_time |
| Heap-allocated time values. More... | |
| struct | ssm_adt1 |
| The struct template of a heap-allocated ADT object. More... | |
| struct | ssm_sv |
| A scheduled variable that supports scheduled updates with triggers. More... | |
| struct | ssm_closure1 |
| The struct template of a heap-allocated closure object. More... | |
| struct | ssm_array1 |
| The struct template of a heap-allocated array of values. More... | |
| struct | ssm_blob1 |
| The struct template of a heap-allocated blob. More... | |
Macros | |
| #define | SSM_THROW(reason) ssm_throw(reason, __FILE__, __LINE__, __func__) |
| Terminate due to a non-recoverable error, with a specified reason. More... | |
| #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) |
| #define | ssm_marshal(v) (ssm_value_t) { .packed_val = ((v) << 1 | 1) } |
| Construct an ssm_value_t from a 31-bit integral value. More... | |
| #define | ssm_unmarshal(v) ((v).packed_val >> 1) |
| Extract an integral value from a packed ssm_value_t. More... | |
| #define | ssm_on_heap(v) (((v).packed_val & 0x1) == 0) |
| Whether a value is on the heap (i.e., is an object). More... | |
| #define | ssm_is_shared(v) !(ssm_on_heap(v) && ((v).heap_ptr->ref_count == 1)) |
| Whether a value is shared, i.e., unsafe to modify. More... | |
| #define | ssm_dup(v) (ssm_on_heap(v) ? ssm_dup_unsafe(v) : (v)) |
| Duplicate a possible heap reference, incrementing its ref count. More... | |
| #define | ssm_drop(v) |
| Drop a reference to a possible heap item, and free it if necessary. More... | |
| #define | ssm_dup_unsafe(v) ((++(v).heap_ptr->ref_count, (v))) |
| Duplicate a heap reference, incrementing its ref count. More... | |
| #define | ssm_drop_unsafe(v) |
| Drop a reference to a heap item, and free it if necessary. More... | |
| #define | SSM_NEVER UINT64_MAX |
| Time indicating something will never happen. More... | |
| #define | SSM_NANOSECOND 1L |
| Ticks per nanosecond. More... | |
| #define | SSM_MICROSECOND (SSM_NANOSECOND * 1000L) |
| Ticks per microsecond. More... | |
| #define | SSM_MILLISECOND (SSM_MICROSECOND * 1000L) |
| Ticks per millisecond. More... | |
| #define | SSM_SECOND (SSM_MILLISECOND * 1000L) |
| Ticks per second. More... | |
| #define | SSM_MINUTE (SSM_SECOND * 60L) |
| Ticks per minute. More... | |
| #define | SSM_HOUR (SSM_MINUTE * 60L) |
| Ticks per hour. More... | |
| #define | ssm_new_time(t) |
| #define | ssm_time_read(v) (container_of((v).heap_ptr, struct ssm_time, mm)->time) |
| Read the heap-allocated time pointed to by an ssm_value_t. More... | |
| #define | ssm_new_adt(fc, tag) |
| #define | ssm_adt_field(v, i) (&*container_of((v).heap_ptr, struct ssm_adt1, mm)->fields)[i] |
| Access the field of an ADT object. More... | |
| #define | ssm_tag(v) (ssm_on_heap(v) ? (v).heap_ptr->info.variant.tag : ssm_unmarshal(v)) |
| Retrieve the tag of an ADT object. More... | |
| #define | ssm_adt_field_count(v) ((v).heap_ptr->info.variant.count) |
| Obtain number of fields in the ADT pointed by v. More... | |
| #define | ssm_adt_size(val_count) (sizeof(struct ssm_adt1) + sizeof(ssm_value_t) * ((val_count)-1)) |
| Compute the size of a heap-allocated ADT. More... | |
| #define | ssm_adt_heap_size(v) ssm_adt_size(ssm_adt_field_count(v)) |
| Compute the size of an ADT already allocated on the heap. More... | |
| #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... | |
| #define | ssm_closure_arg_count(v) (container_of((v).heap_ptr, struct ssm_closure1, mm)->mm.info.vector.count) |
| Obtain the number of argument values owned by a closure. More... | |
| #define | ssm_closure_arg_cap(v) (container_of((v).heap_ptr, struct ssm_closure1, mm)->mm.info.vector.cap) |
| Obtain the number of argument values accommodated by a closure. More... | |
| #define | ssm_closure_func(v) (container_of((v).heap_ptr, struct ssm_closure1, mm)->f) |
| Obtain the enter function pointer of a closure. More... | |
| #define | ssm_closure_argv(v) (&*container_of((v).heap_ptr, struct ssm_closure1, mm)->argv) |
| Retrieve the argument array of a closure. More... | |
| #define | ssm_closure_arg(v, i) ssm_closure_argv(v)[i] |
| Obtain the ith argument of a closure. More... | |
| #define | ssm_closure_size(val_count) (sizeof(struct ssm_closure1) + (sizeof(ssm_value_t) * ((val_count)-1))) |
| Compute the size of a closure object. More... | |
| #define | ssm_closure_heap_size(v) ssm_closure_size(ssm_closure_arg_cap(v)) |
| Compute the size of a closure already allocated on the heap. More... | |
| #define | ssm_closure_push(closure, arg) |
| Add an argument to a closure. More... | |
| #define | ssm_closure_pop(closure) |
| Remove an argument from a closure. More... | |
| #define | ssm_closure_activate(closure, parent, prio, depth, ret) |
| Spawn and schedule a new child process from a fully-applied closure. More... | |
| #define | ssm_new_closure(f, args) |
| #define | ssm_closure_apply_auto(closure, arg, parent, prio, depth, ret) |
| Closure application with automatic memory management. More... | |
| #define | ssm_closure_apply_final_auto(closure, arg, parent, prio, depth, ret) |
| In-place closure application with automatic memory management. More... | |
| #define | ssm_closure_free(closure) |
| Helper to free a closure (without reference counting). More... | |
| #define | ssm_array_len(v) ((v).heap_ptr->info.size) |
| The length of an array pointed by v. More... | |
| #define | ssm_array_elements(v) (&*(container_of((v).heap_ptr, struct ssm_array1, mm)->elements)) |
| Obtain pointer to the array elements payload pointed to by @ a v. More... | |
| #define | ssm_array_element(v, i) (ssm_array_elements(v)[i]) |
| Obtain pointer to the ith element of the array pointed by v. More... | |
| #define | ssm_array_size(count) (sizeof(struct ssm_array1) + sizeof(ssm_value_t) * ((count)-1)) |
| Compute the size of an array with its header. More... | |
| #define | ssm_array_heap_size(v) ssm_array_size(ssm_array_len(v)) |
| Compute the size an array in the heap from an ssm_value_t. More... | |
| #define | ssm_new_array(c) |
| #define | SSM_BLOB_SIZE_SCALE 4 |
| The size resolution for heap-allocated blobs. More... | |
| #define | ssm_blob_size(size) (sizeof(struct ssm_blob1) - SSM_BLOB_SIZE_SCALE + (size)) |
| Compute the size of a blob with its header. More... | |
| #define | ssm_blob_heap_size(v) ssm_blob_size(((v).heap_ptr->info.size) * SSM_BLOB_SIZE_SCALE) |
| Compute the size a blob in the heap. More... | |
| #define | ssm_blob_payload(v) (&*(container_of((v).heap_ptr, struct ssm_blob1, mm)->payload)) |
| Obtain pointer to the payload of a blob from an ssm_value_t. More... | |
| #define | ssm_new_blob(s) |
| #define | member_type(type, member) __typeof__(((type *)0)->member) |
| Obtain the type of a struct member. More... | |
| #define | container_of(ptr, type, member) |
| Obtain the pointer to an outer, enclosing struct. More... | |
Typedefs | |
| typedef enum ssm_error | ssm_error_t |
| Error codes indicating reason for failure. More... | |
| 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... | |
| typedef uint32_t | ssm_word_t |
| Values are 32-bits, the largest supported machine word size. More... | |
| typedef uint64_t | ssm_time_t |
| Absolute time; never to overflow. More... | |
| typedef struct ssm_sv | ssm_sv_t |
| A scheduled variable that supports scheduled updates with triggers. More... | |
| typedef ssm_act_t *(* | ssm_func_t) (ssm_act_t *parent, ssm_priority_t prio, ssm_depth_t depth, ssm_value_t *argv, ssm_value_t *ret) |
| The type signature for all SSM enter functions. More... | |
Enumerations | |
| enum | ssm_error { SSM_INTERNAL_ERROR = 1 , SSM_EXHAUSTED_ACT_QUEUE , SSM_EXHAUSTED_EVENT_QUEUE , SSM_EXHAUSTED_MEMORY , SSM_EXHAUSTED_PRIORITY , SSM_NOT_READY , SSM_INVALID_TIME , SSM_INVALID_MEMORY , SSM_PLATFORM_ERROR } |
| Error codes indicating reason for failure. More... | |
| enum | ssm_kind { SSM_TIME_K = 0 , SSM_ADT_K , SSM_SV_K , SSM_CLOSURE_K , SSM_ARRAY_K , SSM_BLOB_K } |
| The different kinds of heap objects, enumerated. More... | |
Functions | |
| void | ssm_throw (ssm_error_t reason, const char *file, int line, const char *func) |
| Underlying exception handler; must be overridden by each platform. 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... | |
| void | ssm_drop_final (ssm_value_t v) |
| Finalize and free a heap object. More... | |
| void | ssm_dups (size_t cnt, ssm_value_t *arr) |
| Call ssm_dup() on an array of values. More... | |
| void | ssm_drops (size_t cnt, ssm_value_t *arr) |
| Call ssm_drop() on an array of values. More... | |
| ssm_time_t | ssm_now (void) |
| The current model time. More... | |
| ssm_value_t | ssm_new_time_int (ssm_time_t time) |
| Allocate a ssm_time on the heap. More... | |
| ssm_value_t | ssm_new_adt_int (uint8_t field_count, uint8_t tag) |
| Allocate a new ADT object on the heap. 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... | |
| ssm_value_t | ssm_new_closure_int (ssm_func_t f, uint8_t arg_cap) |
| Allocate a closure on the heap. More... | |
| ssm_value_t | ssm_closure_clone (ssm_value_t closure) |
| Create a copy of a closure. More... | |
| void | ssm_closure_apply (ssm_value_t closure, ssm_value_t arg, ssm_act_t *parent, ssm_priority_t prio, ssm_depth_t depth, ssm_value_t *ret) |
| Apply an argument to a closure. More... | |
| void | ssm_closure_apply_final (ssm_value_t closure, ssm_value_t arg, ssm_act_t *parent, ssm_priority_t prio, ssm_depth_t depth, ssm_value_t *ret) |
| Apply an argument to a closure that is used for the last time. More... | |
| ssm_value_t | ssm_new_array_int (uint16_t count) |
| Allocate an array on the heap. More... | |
| ssm_value_t | ssm_new_blob_int (uint16_t size) |
| Allocate a blob on the heap. More... | |
| void * | ssm_mem_alloc (size_t size) |
| Allocate a contiguous range of memory. More... | |
| void | ssm_mem_prealloc (size_t size, size_t num_pages) |
| Preallocate memory pages to ensure capacity in memory pools. More... | |
| void | ssm_mem_free (void *m, size_t size) |
| Deallocate memory allocated by ssm_mem_alloc(). More... | |
Variables | |
| ssm_act_t | ssm_top_parent |
| An activation record for the parent of the top-most routine. More... | |
Detailed Description
Interface to the SSM runtime.
This file contains the public-facing interface of the SSM runtime.
Definition in file ssm.h.
