Action Words

Actions provide a means of asynchronous processing involving message-passing that is lighter-weight than tasks as all computation takes place within a single task and there is none of the complexities of dealing with multiprocessing (except when handling other tasks adding actions to or removing actions from a scheduler that is currently running within a given task, which are minimal in impact). Individual actions do not have their own stacks but rather share the stacks of their parent task.

Message-passing between actions is synchronous; a given action is halted when it is waiting to receive a message or when it is waiting for the message it has sent to be received. Messages can be of any size, and are stored in a buffer provided by the sending task and copied into a buffer provided by the receiving task when received. Note that no order is guaranteed with regard to message-passing, but messages are guaranteed to be eventually received. Note that actions may only send messages to actions within the same schedule; otherwise they will be ignored. Also, if an action is waiting to send a message and that other message is removed from the schedule, the first action is unblocked.

Schedules may be run in any task, may have actions added to or removed from them at any time, and may be stopped safely at any time (the current action’s execution is completed before the schedule stops executing). One note is that a schedule may not be run while it is already running, whether from within the same task or from within a different task.

action

These words are in the module action.

current-schedule

( – schedule )

Get the current schedule.

current-action

( – action )

Get the current action.

current-data

( – data )

Get the current action’s data.

action-schedule@

( action – schedule )

Get the schedule of an action.

action-data@

( action – data )

Get the data of an action.

in-schedule?

( action – flag )

Get whether an action is in a schedule.

schedule-size

( – bytes )

Get the size of a schedule in bytes.

action-size

( – bytes )

Get the size of an action in bytes.

init-schedule

( addr – )

Initialize a schedule at the address addr.

init-action

( data xt addr – )

Initialize an action at the address addr with the initial execution token xt and the data data

add-action

( schedule action – )

Add an action action to schedule schedule. This may be done at any time, including while the schedule is executing.

remove-action

( schedule action – )

Remove an action action from schedule schedule. This may be done at any time, including while the schedule is executing.

send-action

( send-xt addr bytes dest-action – )

Send a message in a buffer at addr of size bytes to action dest-action and set the send execution token to be called once the message is sent or message-sending fails to send-xt. send-xt has the signature ( – ). Sending a message is synchronous; the current action will not execute until either the message is received or the message becomes unable to be sent. dest-action must be in the current schedule or otherwise this routine is a no-op. Sending a message must be done within an executing schedule; messages may not be sent outside of a schedule. Only one message may be sent before control returns to the scheduler; to send multiple messages, send them within subsequent send-xts.

send-action-fail

( send-xt fail-xt addr bytes dest-action – )

Send with failure-handling a message in a buffer at addr of size bytes to action dest-action, set the send execution token to be called once the message is sent to send-xt, and set the failure execution token to be called if message-sending fails to fail-xt. send-xt and fail-xt have the signature ( – ). Sending a message is synchronous; the current action will not execute until either the message is received or the message becomes unable to be sent. dest-action must be in the current schedule or otherwise this routine is a no-op. Sending a message must be done within an executing schedule; messages may not be sent outside of a schedule. Only one message may be sent before control returns to the scheduler; to send multiple messages, send them within subsequent send-xts.

send-action-timeout

( send-xt fail-xt addr bytes dest-action timeout-ticks – )

Send with failure and timeoout-handling a message in a buffer at addr of size bytes to action dest-action with a timeout of timeout-ticks, set the send execution token to be called once the message is sent to send-xt, and set the failure/timeout execution token to be called if message-sending fails to fail-xt. send-xt and fail-xt have the signature ( – ). Sending a message is synchronous; the current action will not execute until either the message is received, the message becomes unable to be sent, or the timeout is reached. dest-action must be in the current schedule or otherwise this routine is a no-op. Sending a message must be done within an executing schedule; messages may not be sent outside of a schedule. Only one message may be sent before control returns to the scheduler; to send multiple messages, send them within subsequent send-xts.

recv-action

( recv-xt addr bytes – )

Receive a message sent to the current action into a buffer at addr of size bytes and set the receive execution token to recv-xt. recv-xt has the signature ( addr bytes src-action – ) where addr is the same addr of the buffer provided earlier, bytes is the actual size of the message received or the size of the buffer, whichever is smaller, and src-action is the source action which sent the message received. Receiving messages is synchronous; the current action will not execute until a message is received. Note that only messages sent from other actions in the same schedule may be received.

recv-action-timeout

( recv-xt timeout-xt addr bytes timeout-ticks – )

Receive a message sent to the current action into a buffer at addr of size bytes and set the receive execution token to recv-xt and the timeout execution token to timeout-xt. recv-xt has the signature ( addr bytes src-action – ) where addr is the same addr of the buffer provided earlier, bytes is the actual size of the message received or the size of the buffer, whichever is smaller, and src-action is the source action which sent the message received. Receiving messages is synchronous; the current action will not execute until either a message is received or timeout-ticks elapses, where then execution will resume at timeout-xt rather than at recv-xt as it would were a message received. Note that only messages sent from other actions in the same schedule may be received.

delay-action

( resume-xt systick-start systick-delay – )

Delay the current action to a time starting from systick-start ticks with a delay of systick-delay ticks and set the resume execution token to resume-xt.

yield-action

( resume-xt – )

Yield the current action and set the resume execution token to resume-xt.

run-schedule

( schedule – )

Run the schedule schedule in the current task. Note that this may not be done if the schedule is already running in any task.

stop-schedule

( schedule – )

Stop the schedule schedule safely, allowing it to finish executing its current action before stopping.

x-already-in-schedule

( – )

Action is already in schedule exception.

x-not-in-schedule

( – )

Action is not in a schedule exception.

x-schedule-already-running

( – )

Schedule is already running exception.

x-operation-set

( – )

Operation is already set for current action exception.