#include "lbm_types.h"
#include "stack.h"
#include "lbm_channel.h"
#include "lbm_flat_value.h"

Include dependency graph for eval_cps.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	eval_context_s

struct	lbm_event_t

Macros
#define	EVAL_CPS_STATE_INIT 0

#define	EVAL_CPS_STATE_PAUSED 1

#define	EVAL_CPS_STATE_RUNNING 2

#define	EVAL_CPS_STATE_STEP 3

#define	EVAL_CPS_STATE_KILL 4

#define	EVAL_CPS_DEFAULT_MAILBOX_SIZE 10

#define	EVAL_CPS_CONTEXT_FLAG_NOTHING (uint32_t)0x0

#define	EVAL_CPS_CONTEXT_FLAG_TRAP (uint32_t)0x1

#define	EVAL_CPS_CONTEXT_FLAG_CONST (uint32_t)0x2

#define	EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS (uint32_t)0x4

#define	EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ (uint32_t)0x8

#define	LBM_THREAD_STATE_READY (uint32_t)0

#define	LBM_THREAD_STATE_BLOCKED (uint32_t)1

#define	LBM_THREAD_STATE_TIMEOUT (uint32_t)2

#define	LBM_THREAD_STATE_SLEEPING (uint32_t)3

#define	LBM_THREAD_STATE_GC_BIT (uint32_t)(1 << 31)

Typedefs
typedef struct eval_context_s	eval_context_t

typedef lbm_value(*	fundamental_fun) (lbm_value , lbm_uint, eval_context_t )

typedef void(*	ctx_fun) (eval_context_t , void , void *)

Enumerations
enum	lbm_event_type_t { LBM_EVENT_FOR_HANDLER = 0 , LBM_EVENT_UNBLOCK_CTX }

Functions
lbm_value	eval_cps_get_env (void)

int	lbm_eval_init (void)

void	lbm_set_eval_step_quota (uint32_t quota)

bool	lbm_eval_init_events (unsigned int num_events)

lbm_cid	lbm_get_event_handler_pid (void)

void	lbm_set_event_handler_pid (lbm_cid pid)

bool	lbm_event_handler_exists (void)

bool	lbm_event (lbm_flat_value_t *fv)

bool	lbm_event_unboxed (lbm_value unboxed)

int	lbm_remove_done_ctx (lbm_cid cid, lbm_value *v)

bool	lbm_wait_ctx (lbm_cid cid, lbm_uint timeout_ms)

lbm_cid	lbm_eval_program (lbm_value lisp)

lbm_cid	lbm_eval_program_ext (lbm_value lisp, unsigned int stack_size)

void	lbm_run_eval (void)

void	lbm_pause_eval (void)

void	lbm_pause_eval_with_gc (uint32_t num_free)

void	lbm_continue_eval (void)

void	lbm_kill_eval (void)

uint32_t	lbm_get_eval_state (void)

void	lbm_set_error_reason (char *error_str)

void	lbm_set_error_suspect (lbm_value suspect)

void	lbm_critical_error (void)

void	lbm_set_critical_error_callback (void(*fptr)(void))

lbm_cid	lbm_create_ctx (lbm_value program, lbm_value env, lbm_uint stack_size, char *name)

void	lbm_block_ctx_from_extension (void)

void	lbm_block_ctx_from_extension_timeout (float s)

void	lbm_undo_block_ctx_from_extension (void)

bool	lbm_unblock_ctx (lbm_cid cid, lbm_flat_value_t *fv)

bool	lbm_unblock_ctx_unboxed (lbm_cid cid, lbm_value unboxed)

void	lbm_running_iterator (ctx_fun f, void , void )

void	lbm_blocked_iterator (ctx_fun f, void , void )

void	lbm_toggle_verbose (void)

void	lbm_set_verbose (bool verbose)

void	lbm_set_usleep_callback (void(*fptr)(uint32_t))

void	lbm_set_timestamp_us_callback (uint32_t(*fptr)(void))

void	lbm_set_ctx_done_callback (void(fptr)(eval_context_t ))

void	lbm_set_printf_callback (int(prnt)(const char ,...))

void	lbm_set_dynamic_load_callback (bool(fptr)(const char , const char **))

lbm_cid	lbm_get_current_cid (void)

eval_context_t *	lbm_get_current_context (void)

bool	lbm_mailbox_change_size (eval_context_t *ctx, lbm_uint new_size)

bool	create_string_channel (char str, lbm_value res)

bool	lift_char_channel (lbm_char_channel_t ch, lbm_value res)

lbm_flash_status	request_flash_storage_cell (lbm_value val, lbm_value *res)

lbm_value	lbm_find_receiver_and_send (lbm_cid cid, lbm_value msg)

int	lbm_perform_gc (void)

Variables
const fundamental_fun	fundamental_table []

Macro Definition Documentation

◆ LBM_THREAD_STATE_READY

#define LBM_THREAD_STATE_READY (uint32_t)0

The eval_context_t struct represents a lispbm process.

Typedef Documentation

◆ ctx_fun

typedef void(* ctx_fun) (eval_context_t *, void *, void *)

A function pointer type to use together with the queue iterators.

Parameters

◆ fundamental_fun

typedef lbm_value(* fundamental_fun) (lbm_value *, lbm_uint, eval_context_t *)

Fundamental operation type

Function Documentation

◆ eval_cps_get_env()

lbm_value eval_cps_get_env ( void )

Get the global environment

Returns: global environment.

◆ lbm_block_ctx_from_extension()

void lbm_block_ctx_from_extension ( void )

Block a context from an extension

◆ lbm_block_ctx_from_extension_timeout()

void lbm_block_ctx_from_extension_timeout ( float s )

Block a context from an extension with a timeout.

Parameters

s	Timeout in seconds.

◆ lbm_blocked_iterator()

void lbm_blocked_iterator	(	ctx_fun	f,
		void *	,
		void *
	)

Iterate over all blocked contexts and apply function on each context.

Parameters

f	Function to apply to each context.
arg1	Pointer argument that can be used to convey information back to user.
arg2	Same as above

◆ lbm_continue_eval()

void lbm_continue_eval ( void )

Resume from being in EVAL_CPS_STATE_PAUSED.

◆ lbm_create_ctx()

lbm_cid lbm_create_ctx	(	lbm_value	program,
		lbm_value	env,
		lbm_uint	stack_size,
		char *	name
	)

Create a context and enqueue it as runnable.

Parameters

program	The program to evaluate in the context.
env	An initial environment.
stack_size	Stack size for the context.
name	Name of thread or NULL.

Returns

◆ lbm_critical_error()

void lbm_critical_error ( void )

Terminate the runtime system in response to an error that it is not possible to recover from.

◆ lbm_eval_init()

int lbm_eval_init ( void )

Initialize the evaluator.

Returns: 1 on success and 0 on failure.

◆ lbm_eval_init_events()

bool lbm_eval_init_events ( unsigned int num_events )

Initialize events

Parameters

num_events The maximum number of unprocessed events.

Returns: true on success, false otherwise.

◆ lbm_eval_program()

lbm_cid lbm_eval_program ( lbm_value lisp )

Creates a context and initializes it with the provided program. The context is added to the ready queue and will start executing when the evaluator is free.

Parameters

lisp	Program to launch

Returns: a context id on success and 0 on failure to launch a context.

◆ lbm_eval_program_ext()

lbm_cid lbm_eval_program_ext	(	lbm_value	lisp,
		unsigned int	stack_size
	)

An extended version of lbm_eval_program that allows specification of stack size to use.

Parameters

lisp	Program to launch.
stack_size	Size of the continuation stack for this context.

Returns: a context id on success and 0 on failure to launch a context.

◆ lbm_event()

bool lbm_event ( lbm_flat_value_t * fv )

Send an event to the registered event handler process. If lbm_event returns false the C code will still be responsible for the flat_value passed into lbm_event. If lbm_event returns true, the LBM runtime system will take responsibility for the freeing of the memory allocated in the flat_value.

Parameters

event	The event to send to the registered handler.
opt_array	An optional array to pass to the event handler.
opt_array_len	Length of array mandatory if array is passed in.

Returns: true if the event was successfully enqueued to be sent, false otherwise.

◆ lbm_event_handler_exists()

bool lbm_event_handler_exists ( void )

Check if an event handler is registerd.

Returns: True if event handler exists, otherwise false.

◆ lbm_event_unboxed()

bool lbm_event_unboxed ( lbm_value unboxed )

Send an unboxed value as an event to the event handler.

Parameters

unboxed. An lbm_value (encoded) such as a symbol. int, uint, character.

Returns: true on success.

◆ lbm_find_receiver_and_send()

lbm_value lbm_find_receiver_and_send	(	lbm_cid	cid,
		lbm_value	msg
	)

deliver a message

Parameters

cid	Process to deliver to.
msg	Message to deliver

Returns: lbm_enc_sym(SYM_NIL) on failure and lbm_enc_sym(SYM_TRUE) on success.

◆ lbm_get_current_cid()

lbm_cid lbm_get_current_cid ( void )

Get the CID of the currently executing context. Should be called from an extension where there is a guarantee that a context is running

◆ lbm_get_current_context()

eval_context_t* lbm_get_current_context ( void )

Get the currently executing context. Should be called from an extension where there is a guarantee that a context is running

◆ lbm_get_eval_state()

uint32_t lbm_get_eval_state ( void )

Get the current state of the evaluator.

Returns: Current state of the evaluator.

◆ lbm_get_event_handler_pid()

lbm_cid lbm_get_event_handler_pid ( void )

Get the process ID for the current event handler.

Returns: process ID on success and -1 if no event handler is registered.

◆ lbm_kill_eval()

void lbm_kill_eval ( void )

This will kill the evaluator on the next iteration.

◆ lbm_mailbox_change_size()

bool lbm_mailbox_change_size	(	eval_context_t *	ctx,
		lbm_uint	new_size
	)

Change the mailbox size for a given context.

Parameters

ctx	The context to change mailbox size for.
new_size	The new size of the mailbox.

Returns: true on success and false otherwise.

◆ lbm_pause_eval()

void lbm_pause_eval ( void )

Indicate that the evaluator should pause at the next iteration. You cannot assume that the evaluator has paused unless you call lbm_get_eval_state and get the return value EVAL_CPS_STATE_PAUSED.

◆ lbm_pause_eval_with_gc()

void lbm_pause_eval_with_gc ( uint32_t num_free )

Pause the evaluator and perform GC if needed.

Parameters

num_free Perform GC if there are less than this many elements free on the heap.

◆ lbm_perform_gc()

int lbm_perform_gc ( void )

Perform garbage collection, If this is called from another thread than the eval thread, evaluation must be paused! Or there will be lots of trouble!

Returns: 1 on success

◆ lbm_remove_done_ctx()

int lbm_remove_done_ctx	(	lbm_cid	cid,
		lbm_value *	v
	)

Remove a context that has finished executing and free up its associated memory.

Parameters

cid	Context id of context to free.
v	Pointer to an lbm_value to store the result computed by the program into. Note that for comples values, GC will free these up the next time it runs.

Returns: 1 if a context was successfully removed otherwise 0.

◆ lbm_run_eval()

void lbm_run_eval ( void )

This function executes the evaluation loop and does not return. lbm_run_eval should be started in a new thread provided by the underlying HAL or OS.

◆ lbm_running_iterator()

void lbm_running_iterator	(	ctx_fun	f,
		void *	,
		void *
	)

Iterate over all ready contexts and apply function on each context.

Parameters

f	Function to apply to each context.
arg1	Pointer argument that can be used to convey information back to user.
arg2	Same as above.

◆ lbm_set_critical_error_callback()

void lbm_set_critical_error_callback ( void(*)(void) fptr )

Set the critical error callback

◆ lbm_set_ctx_done_callback()

void lbm_set_ctx_done_callback ( void(*)(eval_context_t *) fptr )

Set a "done" callback function. This function will be called by the evaluator when a context finishes execution.

Parameters

fptr	Pointer to a "done" function.

◆ lbm_set_dynamic_load_callback()

void lbm_set_dynamic_load_callback ( bool(*)(const char *, const char **) fptr )

Set a callback for dynamically loading code associated with an undefined symbol

◆ lbm_set_error_reason()

void lbm_set_error_reason ( char * error_str )

Provide a description of an error as a string. Use when implementing for example extensions to report an error message to the programmer in case the extension is used incorrectly.

The error string can be allocated in lbm_memory and will in that case be freed when the context that errored is removed.

Parameters

error_str

◆ lbm_set_error_suspect()

void lbm_set_error_suspect ( lbm_value suspect )

Provide the expression that is most suspicious in relation to the error at hand.

Parameters

lbm_value

◆ lbm_set_eval_step_quota()

void lbm_set_eval_step_quota ( uint32_t quota )

Set a new value to use as step quota. This changes the scheduling interval.

Parameters

quota The new quota.

◆ lbm_set_event_handler_pid()

void lbm_set_event_handler_pid ( lbm_cid pid )

Set the event handler process ID.

Parameters

pid	The ID of the process to which events should be sent

◆ lbm_set_printf_callback()

void lbm_set_printf_callback ( int(*)(const char *,...) prnt )

Set a "printf" callback function. This function will be called by the evaluator to report error strings back to the user.

Parameters

fptr	Pointer to a "printf" function.

◆ lbm_set_timestamp_us_callback()

void lbm_set_timestamp_us_callback ( uint32_t(*)(void) fptr )

Set a timestamp callback for use by the evaluator thread.

Parameters

fptr	Pointer to a timestamp generating function.

◆ lbm_set_usleep_callback()

void lbm_set_usleep_callback ( void(*)(uint32_t) fptr )

Set a usleep callback for use by the evaluator thread.

Parameters

fptr	Pointer to a sleep function.

◆ lbm_set_verbose()

void lbm_set_verbose ( bool verbose )

Set verbosity level of lispbm error messages.

Parameters

verbose Boolean to turn verbose errors on or off.

◆ lbm_toggle_verbose()

void lbm_toggle_verbose ( void )

toggle verbosity level of error messages

◆ lbm_unblock_ctx()

bool lbm_unblock_ctx	(	lbm_cid	cid,
		lbm_flat_value_t *	fv
	)

Unblock a context that has been blocked by a C extension Trying to unblock a context that is waiting on a message in a mailbox is not encouraged

Parameters

cid	Lisp process to wake up.
fv	lbm_flat_value to give return as result from the unblocket process.

◆ lbm_unblock_ctx_unboxed()

bool lbm_unblock_ctx_unboxed	(	lbm_cid	cid,
		lbm_value	unboxed
	)

Unblock a context bypassing the event-queue. Since the context will be unblocked in a separate tread it cannot take a composite return value. Only unboxed lbm_values are allowed.

Parameters

cid	Lisp process to inblock.
unboxed	An unboxed lbm_value: char, i, u or symbol type.

Returns: True on successfully unblocking. False otherwise.

◆ lbm_undo_block_ctx_from_extension()

void lbm_undo_block_ctx_from_extension ( void )

Undo a previous call to lbm_block_ctx_from_extension.

◆ lbm_wait_ctx()

bool lbm_wait_ctx	(	lbm_cid	cid,
		lbm_uint	timeout_ms
	)

Wait until a given cid is not present in any of the queues. If you have spawned this cid, you can conclude that it has run to completion or failure.

Parameters

cid	Context id to wait for.
timeout_ms	timeout in ms or 0 for no timeout.

Returns: Result computed by the program running in the context.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ LBM_THREAD_STATE_READY

Typedef Documentation

◆ ctx_fun

◆ fundamental_fun

Function Documentation

◆ eval_cps_get_env()

◆ lbm_block_ctx_from_extension()

◆ lbm_block_ctx_from_extension_timeout()

◆ lbm_blocked_iterator()

◆ lbm_continue_eval()

◆ lbm_create_ctx()

◆ lbm_critical_error()

◆ lbm_eval_init()

◆ lbm_eval_init_events()

◆ lbm_eval_program()

◆ lbm_eval_program_ext()

◆ lbm_event()

◆ lbm_event_handler_exists()

◆ lbm_event_unboxed()

◆ lbm_find_receiver_and_send()

◆ lbm_get_current_cid()

◆ lbm_get_current_context()

◆ lbm_get_eval_state()

◆ lbm_get_event_handler_pid()

◆ lbm_kill_eval()

◆ lbm_mailbox_change_size()

◆ lbm_pause_eval()

◆ lbm_pause_eval_with_gc()

◆ lbm_perform_gc()

◆ lbm_remove_done_ctx()

◆ lbm_run_eval()

◆ lbm_running_iterator()

◆ lbm_set_critical_error_callback()

◆ lbm_set_ctx_done_callback()

◆ lbm_set_dynamic_load_callback()

◆ lbm_set_error_reason()

◆ lbm_set_error_suspect()

◆ lbm_set_eval_step_quota()

◆ lbm_set_event_handler_pid()

◆ lbm_set_printf_callback()

◆ lbm_set_timestamp_us_callback()

◆ lbm_set_usleep_callback()

◆ lbm_set_verbose()

◆ lbm_toggle_verbose()

◆ lbm_unblock_ctx()

◆ lbm_unblock_ctx_unboxed()

◆ lbm_undo_block_ctx_from_extension()

◆ lbm_wait_ctx()