eval_cps.h File Reference

#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:

Go to the source code of this file.

Data Structures
struct	eval_context_s
struct	lbm_event_t

Macros
#define	EVAL_CPS_STATE_NONE   0
#define	EVAL_CPS_STATE_PAUSED   1
#define	EVAL_CPS_STATE_RUNNING   2
#define	EVAL_CPS_STATE_KILL   4
#define	EVAL_CPS_STATE_DEAD   8
#define	EVAL_CPS_STATE_RESET   16
#define	EVAL_CPS_DEFAULT_MAILBOX_SIZE   10
#define	EVAL_CPS_CONTEXT_FLAG_NOTHING   (uint32_t)0x00
#define	EVAL_CPS_CONTEXT_FLAG_TRAP   (uint32_t)0x01
#define	EVAL_CPS_CONTEXT_FLAG_CONST   (uint32_t)0x02
#define	EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS   (uint32_t)0x04
#define	EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ   (uint32_t)0x08
#define	EVAL_CPS_CONTEXT_FLAG_TRAP_UNROLL_RETURN   (uint32_t)0x10
#define	EVAL_CPS_CONTEXT_READER_FLAGS_MASK   (EVAL_CPS_CONTEXT_FLAG_CONST | EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS | EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ)
#define	LBM_THREAD_STATE_READY   (uint32_t)0u
#define	LBM_THREAD_STATE_BLOCKED   (uint32_t)1u
#define	LBM_THREAD_STATE_TIMEOUT   (uint32_t)2u
#define	LBM_THREAD_STATE_SLEEPING   (uint32_t)4u
#define	LBM_THREAD_STATE_RECV_BL   (uint32_t)8u
#define	LBM_THREAD_STATE_RECV_TO   (uint32_t)16u
#define	LBM_THREAD_STATE_GC_BIT   (uint32_t)(1u << 31)
#define	LBM_IS_STATE_TIMEOUT(X)   (X & (LBM_THREAD_STATE_TIMEOUT | LBM_THREAD_STATE_RECV_TO))
#define	LBM_IS_STATE_WAKE_UP_WAKABLE(X)   (X & (LBM_THREAD_STATE_SLEEPING | LBM_IS_STATE_TIMEOUT(X)))
#define	LBM_IS_STATE_UNBLOCKABLE(X)   (X & (LBM_THREAD_STATE_BLOCKED | LBM_THREAD_STATE_TIMEOUT))
#define	LBM_IS_STATE_RECV(X)   (X & (LBM_THREAD_STATE_RECV_BL | LBM_THREAD_STATE_RECV_TO))

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 , LBM_EVENT_DEFINE }

Functions
lbm_value	eval_cps_get_env (void)
void	lbm_add_eval_symbols (void)
bool	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_define (lbm_value key, lbm_flat_value_t *fv)
bool	lbm_event (lbm_flat_value_t *fv)
bool	lbm_event_unboxed (lbm_value unboxed)
bool	lbm_event_queue_is_empty (void)
int	lbm_remove_done_ctx (lbm_cid cid, lbm_value *v)
void	lbm_run_eval (void)
void	lbm_reset_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 (const 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_r (lbm_cid cid)
bool	lbm_unblock_ctx_unboxed (lbm_cid cid, lbm_value unboxed)
void	lbm_all_ctxs_iterator (ctx_fun f, void *arg1, void *arg2)
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_hide_trapped_error (bool hide)
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)
void	lbm_surrender_quota (void)
bool	lbm_mailbox_change_size (eval_context_t *ctx, lbm_uint new_size)
lbm_flash_status	request_flash_storage_cell (lbm_value val, lbm_value *res)
bool	lbm_find_receiver_and_send (lbm_cid cid, lbm_value msg)
int	lbm_perform_gc (void)
void	lbm_request_gc (void)

Variables
const fundamental_fun	fundamental_table []
int(*	lbm_printf_callback )(const char *,...)

Macro Definition Documentation

EVAL_CPS_CONTEXT_FLAG_CONST

#define EVAL_CPS_CONTEXT_FLAG_CONST   (uint32_t)0x02

EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS

#define EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS   (uint32_t)0x04

EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ

#define EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ   (uint32_t)0x08

EVAL_CPS_CONTEXT_FLAG_NOTHING

#define EVAL_CPS_CONTEXT_FLAG_NOTHING   (uint32_t)0x00

EVAL_CPS_CONTEXT_FLAG_TRAP

#define EVAL_CPS_CONTEXT_FLAG_TRAP   (uint32_t)0x01

EVAL_CPS_CONTEXT_FLAG_TRAP_UNROLL_RETURN

#define EVAL_CPS_CONTEXT_FLAG_TRAP_UNROLL_RETURN   (uint32_t)0x10

EVAL_CPS_CONTEXT_READER_FLAGS_MASK

#define EVAL_CPS_CONTEXT_READER_FLAGS_MASK   (EVAL_CPS_CONTEXT_FLAG_CONST | EVAL_CPS_CONTEXT_FLAG_CONST_SYMBOL_STRINGS | EVAL_CPS_CONTEXT_FLAG_INCREMENTAL_READ)

EVAL_CPS_DEFAULT_MAILBOX_SIZE

#define EVAL_CPS_DEFAULT_MAILBOX_SIZE   10

EVAL_CPS_STATE_DEAD

#define EVAL_CPS_STATE_DEAD   8

EVAL_CPS_STATE_KILL

#define EVAL_CPS_STATE_KILL   4

EVAL_CPS_STATE_NONE

#define EVAL_CPS_STATE_NONE   0

EVAL_CPS_STATE_PAUSED

#define EVAL_CPS_STATE_PAUSED   1

EVAL_CPS_STATE_RESET

#define EVAL_CPS_STATE_RESET   16

EVAL_CPS_STATE_RUNNING

#define EVAL_CPS_STATE_RUNNING   2

LBM_IS_STATE_RECV

#define LBM_IS_STATE_RECV

(

X

)

(X & (LBM_THREAD_STATE_RECV_BL | LBM_THREAD_STATE_RECV_TO))

LBM_IS_STATE_TIMEOUT

#define LBM_IS_STATE_TIMEOUT

(

X

)

(X & (LBM_THREAD_STATE_TIMEOUT | LBM_THREAD_STATE_RECV_TO))

LBM_IS_STATE_UNBLOCKABLE

#define LBM_IS_STATE_UNBLOCKABLE

(

X

)

(X & (LBM_THREAD_STATE_BLOCKED | LBM_THREAD_STATE_TIMEOUT))

LBM_IS_STATE_WAKE_UP_WAKABLE

#define LBM_IS_STATE_WAKE_UP_WAKABLE

(

X

)

(X & (LBM_THREAD_STATE_SLEEPING | LBM_IS_STATE_TIMEOUT(X)))

LBM_THREAD_STATE_BLOCKED

#define LBM_THREAD_STATE_BLOCKED   (uint32_t)1u

LBM_THREAD_STATE_GC_BIT

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

LBM_THREAD_STATE_READY

#define LBM_THREAD_STATE_READY   (uint32_t)0u

The eval_context_t struct represents a lispbm process.

LBM_THREAD_STATE_RECV_BL

#define LBM_THREAD_STATE_RECV_BL   (uint32_t)8u

LBM_THREAD_STATE_RECV_TO

#define LBM_THREAD_STATE_RECV_TO   (uint32_t)16u

LBM_THREAD_STATE_SLEEPING

#define LBM_THREAD_STATE_SLEEPING   (uint32_t)4u

LBM_THREAD_STATE_TIMEOUT

#define LBM_THREAD_STATE_TIMEOUT   (uint32_t)2u

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

eval_context_t

typedef struct eval_context_s eval_context_t

fundamental_fun

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

Fundamental operation type

Enumeration Type Documentation

lbm_event_type_t

enum lbm_event_type_t

Enumerator
LBM_EVENT_FOR_HANDLER
LBM_EVENT_UNBLOCK_CTX
LBM_EVENT_DEFINE

Function Documentation

eval_cps_get_env()

lbm_value eval_cps_get_env

(

void

)

Get the global environment

Returns

global environment.

lbm_add_eval_symbols()

void lbm_add_eval_symbols

(

void

)

Add symbols used internally by evaluator.

lbm_all_ctxs_iterator()

void lbm_all_ctxs_iterator	(	ctx_fun	f,
		void *	arg1,
		void *	arg2
	)

Iterate over ALL contexts and apply function on each context. This includes the currently running context, if there is one.

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_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 *	arg1,
		void *	arg2
	)

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()

bool lbm_eval_init

(

void

)

Initialize the evaluator.

Returns

true on success and false 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_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_define()

bool lbm_event_define	(	lbm_value	key,
		lbm_flat_value_t *	fv
	)

Sen an event that causes a definition to be performed at the nect convenience.

Parameters

key	symbol to bind.
fv	Flat value representation of value.

Returns

true if event is successfully added to queue.

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_queue_is_empty()

bool lbm_event_queue_is_empty

(

void

)

Check if the event queue is empty.

Returns

true if event queue is empty, 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()

bool 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

true on success false on failure.

find_receiver_and_send is used for message passing where the semantics is that the oldest message is dropped if the receiver mailbox is full.

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_request_gc()

void lbm_request_gc

(

void

)

Request that the runtime system performs a garbage collection on its earliers convenience. Can be called from any thread and does NOT require that the evaluator is paused.

lbm_reset_eval()

void lbm_reset_eval

(

void

)

Indicate that the evaluator should reset at the next opportunity. You cannot assume that the evaluator has entered reset state unless you call lbm_get_eval_state and get the return value EVAL_CPS_STATE_RESET. While in reset state, all LBM memories should be reinitialized and cleared. Use lbm_continue_eval(), to resume operation after reset.

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 *	arg1,
		void *	arg2
	)

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

(

const 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_hide_trapped_error()

void lbm_set_hide_trapped_error

(

bool

hide

)

Hide error messages for trapped errors

Parameters

hide	true to hide error messages when trapped.

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_surrender_quota()

void lbm_surrender_quota

(

void

)

Surrenders remaining eval quota. Call this from extensions that takes non-trivial amounts of time.

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_r()

bool lbm_unblock_ctx_r

(

lbm_cid

cid

)

Unblock a context bypassing the event-queue. The return value is unchanged from when the context was blocked.

Parameters

cid	Lisp process to unblock.

Returns

True on successfully unblocking. False otherwise.

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 unblock.
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.

request_flash_storage_cell()

lbm_flash_status request_flash_storage_cell	(	lbm_value	val,
		lbm_value *	res
	)

Variable Documentation

fundamental_table

const fundamental_fun fundamental_table[]

extern

lbm_printf_callback

int(* lbm_printf_callback) (const char *,...) ( const char *  ,   ...  )

extern