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)0
#define	LBM_THREAD_STATE_BLOCKED   (uint32_t)1
#define	LBM_THREAD_STATE_TIMEOUT   (uint32_t)2
#define	LBM_THREAD_STATE_SLEEPING   (uint32_t)4
#define	LBM_THREAD_STATE_RECV_BL   (uint32_t)8
#define	LBM_THREAD_STATE_RECV_TO   (uint32_t)16
#define	LBM_THREAD_STATE_GC_BIT   (uint32_t)(1 << 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, LBM_EVENT_RUN_USER_CALLBACK }

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_define (lbm_value key, lbm_flat_value_t *fv)
bool	lbm_event_run_user_callback (void *arg)
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)
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_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 (char *error_str)
void	lbm_set_error_suspect (lbm_value suspect)
void	lbm_critical_error (void)
void	lbm_set_user_callback (void(*fptr)(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_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)
void	lbm_request_gc (void)

Variables
const fundamental_fun	fundamental_table []

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

LBM_THREAD_STATE_GC_BIT

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

LBM_THREAD_STATE_READY

#define LBM_THREAD_STATE_READY   (uint32_t)0

The eval_context_t struct represents a lispbm process.

LBM_THREAD_STATE_RECV_BL

#define LBM_THREAD_STATE_RECV_BL   (uint32_t)8

LBM_THREAD_STATE_RECV_TO

#define LBM_THREAD_STATE_RECV_TO   (uint32_t)16

LBM_THREAD_STATE_SLEEPING

#define LBM_THREAD_STATE_SLEEPING   (uint32_t)4

LBM_THREAD_STATE_TIMEOUT

#define LBM_THREAD_STATE_TIMEOUT   (uint32_t)2

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
LBM_EVENT_RUN_USER_CALLBACK

Function Documentation

create_string_channel()

bool create_string_channel	(	char *	str,
		lbm_value *	res
	)

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

bool lbm_event_run_user_callback

(

void *

arg

)

Send an event causing the user_callback to be run at the next convenience.

Returns

true if event is successfully added to queue.

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_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 *	,
		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_user_callback()

void lbm_set_user_callback

(

void(*)(void *)

fptr

)

Set the arbitrary user function callback

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

lift_char_channel()

bool lift_char_channel	(	lbm_char_channel_t *	ch,
		lbm_value *	res
	)

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[]