The sento Reference Manual

4.1.1 sento/sento.asd

Source

sento.asd.

Parent Component

sento (system).

ASDF Systems

sento.

---

4.1.2 sento/src/atomic/atomic-api.lisp

Source

sento.asd.

Parent Component

atomic (module).

Packages

sento.atomic.

Public Interface

• atomic-cas (generic function).
• atomic-get (generic function).
• atomic-swap (generic function).

---

4.1.3 sento/src/atomic/atomic.lisp

Source

sento.asd.

Parent Component

atomic (module).

Public Interface

• atomic-cas (method).
• atomic-cas (method).
• atomic-get (method).
• atomic-get (method).
• atomic-swap (method).
• atomic-swap (method).
• make-atomic-integer (function).
• make-atomic-reference (function).
• print-object (method).
• print-object (method).

Internals

• %make-atomic-integer (function).
• %make-atomic-reference (function).
• *the-int* (special variable).
• *the-ref* (special variable).
• atomic-integer (structure).
• atomic-integer-cell (reader).
• (setf atomic-integer-cell) (writer).
• atomic-integer-p (function).
• atomic-place (macro).
• atomic-reference (structure).
• atomic-reference-cell (reader).
• (setf atomic-reference-cell) (writer).
• atomic-reference-p (function).
• copy-atomic-integer (function).
• copy-atomic-reference (function).

---

4.1.4 sento/src/config.lisp

Dependency

atomic (module).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.config.

Public Interface

• config-from (function).
• merge-config (function).
• retrieve-keys (function).
• retrieve-section (function).
• retrieve-value (function).

Internals

%merge-config (function).

---

4.1.5 sento/src/wheel-timer.lisp

Dependency

config.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.wheel-timer.

Public Interface

• cancel (function).
• make-wheel-timer (function).
• print-object (method).
• schedule-once (function).
• schedule-recurring (function).
• shutdown-wheel-timer (function).
• wheel-timer (class).

Internals

• timer-hash (reader method).
• (setf timer-hash) (writer method).
• wheel (reader method).
• (setf wheel) (writer method).

---

4.1.6 sento/src/timeutils.lisp

Dependency

wheel-timer.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.timeutils.

Public Interface

• ask-timeout (condition).
• cause (reader method).
• get-current-millis (function).
• make-timer (function).
• wait-cond (function).
• with-waitfor (macro).

Internals

wait-time (reader method).

---

4.1.7 sento/src/miscutils.lisp

Dependency

timeutils.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.miscutils.

Public Interface

• assert-cond (function).
• await-cond (macro).
• collect-backtrace (function).
• filter (function).
• mkstr (function).

---

4.1.8 sento/src/fcomputation.lisp

Dependency

miscutils.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.future.

Public Interface

• complete-p (function).
• error-p (function).
• fawait (function).
• fcompleted (macro).
• fmap (macro).
• frecover (macro).
• fresult (function).
• future (class).
• futurep (function).
• make-future (function).
• print-object (method).
• with-fut (macro).
• with-fut-resolve (macro).

Internals

• %fcompleted (function).
• %fmap (function).
• make-future-plain (function).

---

4.1.9 sento/src/dispatcher-api.lisp

Dependency

fcomputation.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.dispatcher.

Public Interface

• dispatch (generic function).
• dispatch-async (generic function).
• stop (generic function).
• workers (generic function).

---

4.1.10 sento/src/queue/queue.lisp

Source

sento.asd.

Parent Component

queue (module).

Packages

sento.queue.

Public Interface

• emptyq-p (generic function).
• initialize-instance (method).
• popq (generic function).
• pushq (generic function).
• queue-bounded (class).
• queue-full-error (condition).
• queued-count (generic function).

Internals

• queue (reader method).
• queue-base (class).

---

4.1.11 sento/src/queue/queue-locked.lisp

Source

sento.asd.

Parent Component

queue (module).

Public Interface

• emptyq-p (method).
• popq (method).
• pushq (method).
• queue-unbounded (class).

Internals

• copy-queue (function).
• dequeue (function).
• emptyp (function).
• enqueue (function).
• make-queue (function).
• queue (structure).
• queue-head (reader).
• (setf queue-head) (writer).
• queue-p (function).
• queue-tail (reader).
• (setf queue-tail) (writer).

---

4.1.12 sento/src/mbox/message-box.lisp

Source

sento.asd.

Parent Component

mbox (module).

Packages

sento.messageb.

Public Interface

• initialize-instance (method).
• initialize-instance (method).
• initialize-instance (method).
• message-box/bt (class).
• message-box/dp (class).
• print-object (method).
• stop (generic function).
• submit (generic function).

Internals

• call-handler-fun (function).
• copy-message-item/bt (function).
• copy-message-item/dp (function).
• dispatch/noreply (function).
• dispatch/reply (function).
• dispatch/reply/no-timeout (function).
• dispatch/reply/timeout (function).
• dispatcher (reader method).
• dispatcher-exec-fun (function).
• handle-popped-item (function).
• make-message-item/bt (function).
• make-message-item/dp (function).
• max-queue-size (reader method).
• message-box-base (class).
• message-item/bt (structure).
• message-item/bt-cancelled-p (reader).
• (setf message-item/bt-cancelled-p) (writer).
• message-item/bt-handler-fun-args (reader).
• (setf message-item/bt-handler-fun-args) (writer).
• message-item/bt-handler-result (reader).
• (setf message-item/bt-handler-result) (writer).
• message-item/bt-message (reader).
• (setf message-item/bt-message) (writer).
• message-item/bt-p (function).
• message-item/bt-time-out (reader).
• (setf message-item/bt-time-out) (writer).
• message-item/bt-withreply-cvar (reader).
• (setf message-item/bt-withreply-cvar) (writer).
• message-item/bt-withreply-lock (reader).
• (setf message-item/bt-withreply-lock) (writer).
• message-item/bt-withreply-p (reader).
• (setf message-item/bt-withreply-p) (writer).
• message-item/dp (structure).
• message-item/dp-cancelled-p (reader).
• (setf message-item/dp-cancelled-p) (writer).
• message-item/dp-handler-fun-args (reader).
• (setf message-item/dp-handler-fun-args) (writer).
• message-item/dp-handler-result (reader).
• (setf message-item/dp-handler-result) (writer).
• message-item/dp-message (reader).
• (setf message-item/dp-message) (writer).
• message-item/dp-p (function).
• message-item/dp-time-out (reader).
• (setf message-item/dp-time-out) (writer).
• message-processing-loop (function).
• name (reader method).
• pop-queue-and-process (function).
• process-queue-item (function).
• submit/no-reply (function).
• submit/reply (function).
• wait-and-probe-for-msg-handler-result (function).

---

4.1.13 sento/src/actor-cell.lisp

Dependency

mbox (module).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.actor-cell.

Public Interface

• *self* (special variable).
• *sender* (special variable).
• *state* (special variable).
• actor-cell (class).
• call (function).
• cast (function).
• handle-call (generic function).
• handle-cast (generic function).
• initialize-instance (method).
• msgbox (reader method).
• (setf msgbox) (writer method).
• name (reader method).
• print-object (method).
• running-p (function).
• state (reader method).
• stop (generic function).

Internals

• actor-cell-state (structure).
• actor-cell-state-p (function).
• actor-cell-state-running (reader).
• (setf actor-cell-state-running) (writer).
• copy-actor-cell-state (function).
• handle-message (function).
• handle-message-internal (function).
• handle-message-user (function).
• make-actor-cell-state (function).
• submit-message (function).
• with-sender (macro).

---

4.1.14 sento/src/actor-api.lisp

Dependency

actor-cell.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.actor.

Public Interface

• actor (class).
• after-stop (generic function).
• ask (generic function).
• ask-s (generic function).
• become (generic function).
• context (generic reader).
• (setf context) (writer method).
• make-actor (generic function).
• path (generic function).
• pre-start (generic function).
• tell (generic function).
• unbecome (generic function).
• unwatch (generic function).
• watch (generic function).
• watchers (generic reader).

Internals

receive (reader method).

---

4.1.15 sento/src/eventstream-api.lisp

Dependency

actor-api.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.eventstream.

Public Interface

• publish (generic function).
• subscribe (generic function).
• unsubscribe (generic function).

---

4.1.16 sento/src/actor-system-api.lisp

Dependency

eventstream-api.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.actor-system.

Public Interface

*default-config* (special variable).

---

4.1.17 sento/src/actor-context-api.lisp

Dependency

actor-system-api.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.actor-context.

Public Interface

• actor-name-exists (condition).
• actor-of (generic function).
• all-actors (generic function).
• find-actors (generic function).
• notify (generic function).
• shutdown (generic function).
• stop (generic function).

Internals

name (reader method).

---

4.1.18 sento/src/fasync-completed.lisp

Dependency

actor-context-api.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.async-future.

Public Interface

fasync-completed (macro).

---

4.1.19 sento/src/actor.lisp

Dependency

fasync-completed.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Public Interface

• *self* (symbol macro).
• *sender* (symbol macro).
• *state* (symbol macro).
• actor-of (method).
• after-stop (method).
• all-actors (method).
• ask (method).
• ask-s (method).
• become (method).
• find-actors (method).
• handle-call (method).
• handle-cast (method).
• make-actor (method).
• path (method).
• pre-start (method).
• print-object (method).
• publish (method).
• reply (function).
• stop (method).
• subscribe (method).
• system (method).
• tell (method).
• unbecome (method).
• unsubscribe (method).
• unwatch (method).
• watch (method).

Internals

• async-waitor-actor (class).
• finalize-initialization (function).
• name (method).
• notify-watchers-about-stop (function).
• stop-children (function).
• with-waiting-actor (macro).

---

4.1.20 sento/src/agent.lisp

Dependency

actor.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.agent.

Public Interface

• agent (class).
• agent-get (function).
• agent-get-quick (function).
• agent-stop (function).
• agent-update (function).
• agent-update-and-get (function).
• make-agent (function).

Internals

receive (function).

---

4.1.21 sento/src/eventstream.lisp

Dependency

agent.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Public Interface

• eventstream (class).
• make-eventstream (function).
• publish (method).
• subscribe (method).
• unsubscribe (method).

Internals

• ev-receive (function).
• subscribers (reader method).
• subscribers-for (function).

---

4.1.22 sento/src/fsm.lisp

Dependency

eventstream.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.fsm.

Public Interface

• *event-data* (special variable).
• *next-state-data* (special variable).
• *received-event* (special variable).
• *state-data* (special variable).
• fsm (class).
• goto-state (macro).
• make-fsm (function).
• on-event (macro).
• on-transition (macro).
• stay-on-state (macro).
• when-state (macro).
• when-unhandled (macro).

Internals

• %receive (function).
• %setup-timeouts (function).
• *current-state* (special variable).
• *event-was-handled-by-goto* (special variable).
• *event-was-handled-by-stay* (special variable).
• copy-fsm-state (function).
• event-handling-fun (reader method).
• fsm-state (structure).
• fsm-state-data (reader).
• (setf fsm-state-data) (writer).
• fsm-state-p (function).
• fsm-state-state (reader).
• (setf fsm-state-state) (writer).
• make-fsm-state (function).
• timeouts (reader method).

---

4.1.23 sento/src/tasks.lisp

Dependency

fsm.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.tasks.

Public Interface

• *task-context* (special variable).
• *task-dispatcher* (special variable).
• task (class).
• task-async (function).
• task-async-stream (function).
• task-await (function).
• task-shutdown (function).
• task-start (function).
• task-yield (function).
• with-context (macro).

Internals

make-task (function).

---

4.1.24 sento/src/router.lisp

Dependency

tasks.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.router.

Public Interface

• add-routee (function).
• ask (method).
• ask-s (method).
• make-router (function).
• routees (function).
• router (class).
• stop (function).
• strategy-fun (reader method).
• tell (method).

Internals

• get-strategy-fun (function).
• get-strategy-index (function).
• make-random-strategy (function).
• make-round-robin-strategy (function).

---

4.1.25 sento/src/stash.lisp

Dependency

router.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.stash.

Public Interface

• has-stashed-messages-p (function).
• stash (function).
• stashing (class).
• unstash-all (function).

Internals

stashed-messages (reader method).

---

4.1.26 sento/src/dispatcher.lisp

Dependency

stash.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Public Interface

• dispatch (method).
• dispatch-async (method).
• dispatch-worker (class).
• dispatcher-base (class).
• identifier (reader method).
• initialize-instance (method).
• make-dispatcher (function).
• make-dispatcher-worker (function).
• print-object (method).
• shared-dispatcher (class).
• stop (method).
• workers (method).

Internals

receive (function).

---

4.1.27 sento/src/actor-context.lisp

Dependency

dispatcher.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Public Interface

• actor-context (class).
• actor-of (method).
• all-actors (method).
• find-actors (method).
• id (reader method).
• make-actor-context (function).
• notify (method).
• shutdown (method).
• stop (method).
• system (reader method).

Internals

• %actor-of (function).
• %add-actor (function).
• %create-actor (function).
• %find-actor-by-name (function).
• %find-actors (function).
• %get-shared-dispatcher (function).
• %message-box-for-dispatcher-id (function).
• %remove-actor (function).
• %verify-actor (function).
• actors (method).

---

4.1.28 sento/src/actor-system.lisp

Dependency

actor-context.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Public Interface

• actor-of (method).
• actor-system (class).
• all-actors (method).
• dispatchers (reader method).
• evstream (reader method).
• find-actors (method).
• initialize-instance (method).
• make-actor-system (function).
• print-object (method).
• publish (method).
• register-dispatcher (function).
• register-new-dispatcher (function).
• scheduler (reader method).
• shutdown (method).
• stop (method).
• subscribe (method).
• unsubscribe (method).

Internals

• %actor-of (function).
• %all-actors (function).
• %find-actors (function).
• %get-dispatcher-config (function).
• %get-eventstream-config (function).
• %get-scheduler-config (function).
• %get-timeout-timer-config (function).
• %register-config (function).
• %register-dispatchers (function).
• %register-eventstream (function).
• %register-scheduler (function).
• %register-timeout-timer (function).
• actor-context-for-key (function).
• config (reader method).
• (setf config) (writer method).
• internal-actor-context (reader method).
• timeout-timer (reader method).
• user-actor-context (reader method).

---

4.1.29 sento/src/agent-usecase/agent-usecase-commons.lisp

Source

sento.asd.

Parent Component

agent-usecase (module).

Packages

sento.agent.usecase-commons.

Public Interface

• make-model (function).
• model (structure).
• model-err-fun (reader).
• (setf model-err-fun) (writer).
• model-object (reader).
• (setf model-object) (writer).
• with-get-handler (macro).
• with-update-handler (macro).

Internals

• copy-model (function).
• model-p (function).

---

4.1.30 sento/src/agent-usecase/hash-agent.lisp

Source

sento.asd.

Parent Component

agent-usecase (module).

Packages

sento.agent.hash.

Public Interface

• agent-clrhash (function).
• agent-dohash (function).
• (setf agent-gethash) (setf expander).
• agent-gethash (function).
• agent-remhash (function).
• make-hash-agent (function).

Internals

agent-puthash (function).

---

4.1.31 sento/src/agent-usecase/array-agent.lisp

Source

sento.asd.

Parent Component

agent-usecase (module).

Packages

sento.agent.array.

Public Interface

• agent-delete (function).
• agent-doarray (function).
• (setf agent-elt) (setf expander).
• agent-elt (function).
• agent-pop (function).
• agent-push (function).
• agent-push-and-getidx (function).
• make-array-agent (function).

Internals

agent-set (function).

---

4.1.32 sento/src/package.lisp

Dependency

agent-usecase (module).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.user.

---

6.1.1 Special variables

Special Variable: *default-config* ¶

The default config used when creating an ‘asys:actor-system‘.
The actor-system constructor allows to provide custom config options that override the default.

Package

sento.actor-system.

Source

actor-system-api.lisp.

Special Variable: *event-data* ¶

Dynamically binds event data when msg/event was sent with data (‘cons’)

Package

sento.fsm.

Source

fsm.lisp.

Special Variable: *next-state-data* ¶

Dynamically binds the next state data (‘on-transition’).
Effectively same as ‘*event-data*’ but should be used in different context.

Package

sento.fsm.

Source

fsm.lisp.

Special Variable: *received-event* ¶

Dynamically binds the received event (message).

Package

sento.fsm.

Source

fsm.lisp.

Special Variable: *self* ¶

The ’own’ actor instance. Dynamically bound and available upon calling ‘receive‘ function.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Special Variable: *sender* ¶

The ‘*sender*‘ is dynamically bound and available in ‘receive‘ function, when it is known.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Special Variable: *state* ¶

The ’state’ of the actor. Dynamically bound and available in ‘receive‘ function.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Special Variable: *state-data* ¶

Dynamically binds the current state data.

Package

sento.fsm.

Source

fsm.lisp.

Special Variable: *task-context* ¶

Optionally set this globally to use the API without using ‘with-context‘.

Package

sento.tasks.

Source

tasks.lisp.

Special Variable: *task-dispatcher* ¶

Optionally set a dispatcher id. Same applies here as for ‘*task-context*‘.

Package

sento.tasks.

Source

tasks.lisp.

---

6.1.2 Symbol macros

Symbol Macro: *self* ¶

Package

sento.actor.

Source

actor.lisp.

Symbol Macro: *sender* ¶

Package

sento.actor.

Source

actor.lisp.

Symbol Macro: *state* ¶

Package

sento.actor.

Source

actor.lisp.

---

6.1.3 Macros

Macro: await-cond (max-time &body body) ¶

Awaits condition. Probes repeatedly.
If after ‘max-time’ condition is not ‘t’ it is considered failed.

Package

sento.miscutils.

Source

miscutils.lisp.

Macro: fasync-completed (future context dispatcher-id (result) &body body) ¶

Asynchronous future completion handler.

This work essentially the same as ‘future:fcompleted‘ except that the completion function executes in a different execution context. The ’execution-context’ is a dispatcher (‘disp:dispatcher‘) registered in ‘asys:actor-system‘.
It is here identified using ‘dispatcher-id‘ (the defailt dispatcher identifier is ‘:shared‘).
The additional parameter ‘context‘ can be the actor-system itself, an ‘ac:actor-context‘ or an ‘act:actor‘ instance.

If the completion handler should execute on the caller thread, then ‘future:fcompleted‘ should be used.

If the ‘future‘ is already complete then the ‘body‘ executes immediately.
‘result‘ represents the future result.
‘body‘ is executed when future completed.
Returns the future.

Example:

“‘
(fasync-completed (with-fut (sleep .5) 1) asys :shared
(result)
(format t "Future result ~a~%" result))
“‘

Package

sento.async-future.

Source

fasync-completed.lisp.

Macro: fcompleted (future (result) &body body) ¶

Completion handler on the given ‘future‘.

If the ‘future‘ is already complete then the ‘body‘ executes immediately.
‘result‘ represents the future result.
‘body‘ is executed when future completed.
Returns the future.

Notes on execution context:
By calling ‘fcompleted‘ a completion function is installed on the ‘future‘.
If the ‘future‘s execute function is not delaying or called by the same thread as the one calling ‘fcompleted‘,
then ‘body‘ is called by the callers thread.
If, however, the ‘future‘ is delaying and doing computation in another thread and later also resolving the ‘future‘ in that thread (this depends on how the ‘future‘ is defined), then the ‘body‘ form is executed by the thread that is resolving the ‘future‘.

Example:

“‘
(fcompleted (with-fut
(sleep .5)
1)
(result)
(format t "Future result ~a~%" result))
“‘

Package

sento.future.

Source

fcomputation.lisp.

Macro: fmap (future (result) &body body) ¶

‘fmap‘ maps a future.

‘future‘ is the future that is mapped.
‘result‘ is the result of the future when it completed.
‘body‘ is the form that executes when the future is completed. The result of ‘body‘ generates a new future.

Notes on execution context:
By calling ‘fmap‘ a mapping function is installed on the ‘future‘.
If the ‘future‘s execute function is not delaying or called by the same thread as the one calling ‘fmap‘,
then ‘body‘ is called by the callers thread.
If, however, the ‘future‘ is delaying and doing computation in another thread and later also resolving the ‘future‘ in that thread (this depends on how the ‘future‘ is defined), then the ‘body‘ form is executed by the thread that is resolving the ‘future‘.

Example:

“‘
(fmap (with-fut 0) (result)
(1+ result))
“‘

Package

sento.future.

Source

fcomputation.lisp.

Macro: frecover (future &rest handler-forms) ¶

Catch errors in futures using ‘frecover‘ It works similar to ‘handler-case‘.

Example:

“‘
(fresult
(frecover
(-> (with-fut 0)
(fmap (value)
(declare (ignore value)) (error "foo")))
(fmap (value)
(+ value 1))))
(error (c) (format nil "~a" c)))) “‘

Package

sento.future.

Source

fcomputation.lisp.

Macro: goto-state (next-state &optional data) ¶

‘goto-state‘ Macro

The ‘goto-state‘ macro is used to transition the FSM (Finite State Machine) to a specified state, with optional data setting for the state model. This macro simplifies state management by providing a direct mechanism to switch states and update state-specific data.

**Parameters**

- ‘state‘: The target state to which the FSM should transition. This can be a symbol or any other datatype representing the state, consistent with the FSM’s state representation.

- ‘data‘: An optional parameter to set the data associated with the new state. This allows for updating the state model with relevant information during the transition.

**Description**

The ‘goto-state‘ macro facilitates explicit state transitions and optionally updates the state model’s data. It is typically invoked in response to specific conditions or events, allowing dynamic integration with other FSM constructs like ‘when-state‘ or ‘on-event‘.

**Usage Example**

“‘lisp
(when-state (’idle :test #’eq :timeout-s 5)
(on-event (’start)
(goto-state ’active ’("Session ID: 123"))
(perform-initialization)))

(when-state (’active :test #’eq)
(on-event (’stop)
(goto-state ’idle ’("Clean exit"))
(perform-cleanup)))
“‘

In this example:
- The FSM transitions to the ‘active‘ state with associated data ‘"Session ID: 123"‘ upon receiving a ‘start‘ event while in the ‘idle‘ state, executing ‘perform-initialization‘.
- It transitions back to the ‘idle‘ state with data ‘"Clean exit"‘ when the ‘stop‘ event occurs while the FSM is in the ‘active‘ state, executing ‘perform-cleanup‘.

**Notes**

- Ensure that ‘state‘ is valid within the FSM’s state space and that the transition complies with the FSM’s logic and rules.
- The ‘data‘ parameter is optional, but when used, should be structured appropriately to fit the state model’s requirements.

The ‘goto-state‘ macro, with its optional ‘data‘ capability, enhances flexibility and precision in managing FSM state transitions and data updates. Adjust the usage examples and structure to align with your FSM’s specific needs and design.

Package

sento.fsm.

Source

fsm.lisp.

Macro: on-event ((event &key test) &body body) ¶

‘on-event‘ Macro

The ‘on-event‘ macro defines actions to be executed when specific events occur within an FSM (Finite State Machine). It is often used within the ‘when-state‘ macro to enable conditional execution based on state and optional timeout constraints.

**Parameters**

- ‘event‘: The event name or identifier to be monitored. This argument specifies which event should trigger the execution of the provided body.

- ‘:state-timeout‘: A tag indicating that the execution of this event’s actions is subject to the ‘:timeout-s‘ specified in a surrounding ‘when-state‘ macro.

- ‘body‘: One or more expressions representing the actions to be executed when the specified event occurs.

**Description**

The ‘on-event‘ macro facilitates event-driven actions within FSMs. When used within a ‘when-state‘ block and tagged with ‘:state-timeout‘, it ensures that the actions are executed within a specified time period after the event occurs, contingent on the current state of the FSM.

**Usage Example**

“‘lisp
(when-state (’active :test #’eq :timeout-s 10)
(on-event ’start :state-timeout
(start-activity))
(on-event ’stop
(stop-activity)))
“‘

In this example:
- The ‘start-activity‘ action is executed when the ‘start‘ event occurs, provided the FSM is in the ‘active‘ state within the 10-second timeout duration.
- The ‘stop-activity‘ is triggered by a ‘stop‘ event without timeout constraints.

**Notes**

- ‘:state-timeout‘ indicates that the timeout from ‘when-state‘ should apply to this event’s execution.
- Ensure the event detection mechanism within your FSM can recognize and handle the specified ‘event‘ argument.

Use ‘on-event‘ macros within ‘when-state‘ to manage event responses systematically and within time constraints defined for specific states. Adjust the actions and logic as necessary for your FSM’s behavior.

Package

sento.fsm.

Source

fsm.lisp.

Macro: on-transition ((transition &key test) &body body) ¶

‘on-transition‘ Macro

The ‘on-transition‘ macro defines actions to be executed when a specific state transition occurs within an FSM (Finite State Machine). It uses customizable test functions to determine when a transition has taken place.

**Parameters**

- ‘transition‘: A cons cell or similar paired structure representing the transition, with the car as the starting state and the cdr as the destination state.

- ‘:test‘: A key parameter specifying the function used to compare states. Defaults to ‘#’eq‘, allowing for custom comparison logic if needed.

- ‘body‘: One or more expressions that are executed when the specified transition is detected.

**Description**

The ‘on-transition‘ macro provides a mechanism for executing specific actions when the FSM undergoes a particular state transition, as identified by changes in the state model from a starting to an ending state. This macro depends on events being handled by a state transition (‘goto-state‘), and uses test functions to match state values.

**Usage Example**

“‘lisp
(on-transition ((’idle . ’active) :test #’eq)
(log:info "Transitioned from idle to active")
(initialize-resources))

(on-transition ((’active . ’completed) :test #’eq)
(log:info "Transitioned from active to completed")
(cleanup-resources))
“‘

In these examples:
- The first block logs the transition from ‘idle‘ to ‘active‘ and performs resource initialization when this transition occurs.
- The second block logs the transition from ‘active‘ to ‘completed‘ and performs cleanup.

**Notes**

- ‘:test‘: Customize the comparison logic to fit the FSM’s state representations, especially if using complex or non-standard states.
- The macro relies on transitions being marked by the handling of events through ‘goto-state‘.

Utilize the ‘on-transition‘ macro to effectively manage and isolate logic specific to state transitions, ensuring that your FSM operates smoothly and predictably through defined state changes. Adjust the body of transitions to align with the goals and behavior of your FSM system.

Package

sento.fsm.

Source

fsm.lisp.

Macro: stay-on-state (&optional data) ¶

‘stay-on-state‘ Macro

The ‘stay-on-state‘ macro is used to maintain the FSM (Finite State Machine) in its current state, with an option to update the state’s associated data. This is useful for situations where the state needs to persist while its data is updated.

**Parameters**

- ‘data‘: An optional parameter to update the data related to the current state. This allows for modifying the state model with new information without changing the state itself.

**Description**

The ‘stay-on-state‘ macro provides a way to remain in the current state of an FSM while updating any associated data. It can be used in reaction to specific events or conditions, maintaining state continuity while making data adjustments.

**Usage Example**

“‘lisp
(when-state (’processing :test #’eq)
(on-event (’update)
(stay-on-state ’("Progress: 50%"))
(log-update)))

(when-state (’processing :test #’eq)
(on-event (’complete)
(goto-state ’completed ’("Finished successfully"))))
“‘

In this example:
- The ‘stay-on-state‘ macro is used to remain in the ‘processing‘ state while updating the progress data to ‘"Progress: 50%"‘ upon an ‘update‘ event.
- Transition to the ‘completed‘ state occurs when the ‘complete‘ event is triggered, updating the state and its data.

**Notes**

- The ‘data‘ parameter is optional but should be structured to fit the requirements of the state model.
- Use this macro to ensure state persistence with updated data when necessary.

Integrate the ‘stay-on-state‘ macro into your FSM to handle cases where the state should remain unchanged but its data requires updates. Adjust examples as needed to fit your FSM system.

Package

sento.fsm.

Source

fsm.lisp.

Macro: when-state ((state &key test timeout-s) &body body) ¶

‘when-state‘ Macro

The ‘when-state‘ macro is used to conditionally execute a body of code when a defined condition on the FSM’s (Finite State Machine) current state is met, with support for custom predicates and timeout management for nested ‘on-event‘ macros.

**Parameters**

- ‘state‘: An arbitrary value or structure that represents the state to be checked against the FSM’s current state. The usage and type should align with the ‘:test‘ function.

- ‘:test‘: A predicate function used to evaluate if the FSM’s current state matches the ‘state‘ argument. The default is ‘#’eq‘, but can be customized with other functions or lambdas.

- ‘:timeout-s‘: An optional timeout in seconds that is applied to ‘on-event‘ macro calls tagged with ‘:state-timeout‘ within the body.

- ‘body‘: One or more forms, typically including ‘on-event‘ macro definitions, executed if the state condition is satisfied.

**Description**

‘when-state‘ enables dynamic state-based programming within FSMs, allowing for flexible condition evaluation with customizable predicate functions. It also manages execution timeouts for actions specified within nested ‘on-event‘ calls. The ‘:timeout-s‘ parameter, when used with the ‘:state-timeout‘ tag, ensures operations are constrained to a specified period.

**Usage Example**

“‘lisp
(when-state (’active :test #’eq :timeout-s 10)
(on-event (’start) :state-timeout
(start-activity))
(on-event (’stop)
(stop-activity)))
“‘

In this example:
- ‘start-activity‘ is executed if the current FSM state is exactly ‘’active‘, using ‘:test #’eq‘, within the 10-second window specified by ‘:timeout-s‘ and tagged with ‘:state-timeout‘.
- ‘stop-activity‘ runs upon receiving a ‘stop‘ event, without timeout constraints.

**Notes**

- Adjust the ‘:test‘ predicate to suit the structure and type of your ‘state‘ input as needed.
- ‘:timeout-s‘ specifies a duration within which tagged events should occur, integrating with the ‘on-event‘ macro.
- Ensure that each ‘on-event‘ is properly enclosed in parentheses, reflecting its syntax.

Use the appropriate predicate function to match the ‘state‘ argument’s format, ensuring meaningful and effective FSM operations.

Package

sento.fsm.

Source

fsm.lisp.

Macro: when-unhandled ((event &key test) &body body) ¶

‘when-unhandled‘ Macro

The ‘when-unhandled‘ macro defines actions to be executed when an event has not been handled by any prior ‘stay-on-state‘ or ‘goto-state‘ operations within an FSM (Finite State Machine).

**Parameters**

- ‘event‘: The event that should trigger the body if it remains unhandled by other mechanisms in the FSM.

- ‘:test‘: A key parameter specifying the function used to compare the received event with the specified event. Defaults to ‘#’eq‘, allowing for custom comparison logic.

- ‘body‘: One or more expressions to execute when the specified event is unhandled by ‘stay-on-state‘ or ‘goto-state‘ actions.

**Description**

The ‘when-unhandled‘ macro is designed to catch events that have not been processed by ‘stay-on-state‘ or ‘goto-state‘. It provides a fallback mechanism that ensures specific actions are taken for such unhandled events, using a specified test function to determine event equivalency.

**Usage Example**

“‘lisp
(when-unhandled (’start :test #’eq)
(log:error "Start event was unhandled")
(notify-admin))

(when-unhandled (’disconnect :test #’eq)
(log:warn "Unhandled disconnect event")
(attempt-reconnect))
“‘

In these examples:
- The first block logs an error and notifies an admin if the ‘start‘ event remains unhandled, using the default ‘#’eq‘ function for testing.
- The second block logs a warning and attempts to reconnect for an unhandled ‘disconnect‘ event, also using ‘#’eq‘.

**Notes**

- Utilize the ‘test‘ parameter to customize how events are determined as equivalent when necessary.
- ‘when-unhandled‘ is essential for capturing and managing scenarios where standard state transitions do not account for all event possibilities.
- Is it possible to use ‘goto-state‘ in ‘body‘.

Integrate the ‘when-unhandled‘ macro to ensure your FSM handles any unexpected or default cases robustly and flexibly. Adjust the body actions and events as needed for your specific requirements and FSM design.

Package

sento.fsm.

Source

fsm.lisp.

Macro: with-context ((context &optional dispatcher) &body body) ¶

‘with-context‘ creates an environment where the ‘tasks‘ package functions should be used in.
‘context‘ can be either an ‘asys:actor-system‘, an ‘ac:actor-context‘, or an ‘act:actor‘ (or subclass).
‘dispatcher‘ specifies the dispatcher where the tasks is executed in (like thread-pool).
The tasks created using the ‘tasks‘ functions will then be created in the given context.

Example:

“‘elisp
;; create actor-system
(defparameter *sys* (make-actor-system))

(with-context (*sys*)
(task-yield (lambda () (+ 1 1))))

=> 2 (2 bits, #x2, #o2, #b10)

“‘

Since the default ‘:shared‘ dispatcher should mainly be used for the message dispatching,
but not so much for longer running tasks it is possible to create an actor system with additional
dispatchers. This additional dispatcher can be utilized for ‘tasks‘. Be aware that the config as used below is merged with the ‘asys:*default-config*‘ which means that the dispatcher ‘:foo‘ here is really an additional dispatcher.

“‘
;; create actor-system with additional (custom) dispatcher
(defparameter *sys* (asys:make-actor-system ’(:dispatchers (:foo (:workers 16)))))

(with-context (*sys* :foo)
(task-yield (lambda () (+ 1 1))))

“‘

Package

sento.tasks.

Source

tasks.lisp.

Macro: with-fut (&body body) ¶

Convenience macro for creating a ‘future‘.

The ‘future‘ will be resolved with the result of the body form.

Package

sento.future.

Source

fcomputation.lisp.

Macro: with-fut-resolve (&body body) ¶

Convenience macro for creating a ‘future‘ that must be resolved manually via ‘fresolve‘.

This allows to spawn threads or other asynchronous operations as part of ‘body‘. However, you have to ‘resolve‘ the future eventually by applying a result on ‘resolve‘.

Example:

“‘
(with-fut-resolve
(bt2:make-thread
(lambda ()
(let ((result (do-some-lengthy-calculation)))
(fresolve result)))))
“‘

Package

sento.future.

Source

fcomputation.lisp.

Macro: with-get-handler (&body body) ¶

Package

sento.agent.usecase-commons.

Source

agent-usecase-commons.lisp.

Macro: with-update-handler (&body body) ¶

Package

sento.agent.usecase-commons.

Source

agent-usecase-commons.lisp.

Macro: with-waitfor ((wait-time) &body body) ¶

Spawns thread with timeout. Blocks until computation is done, or timeout elapsed.

Package

sento.timeutils.

Source

timeutils.lisp.

---

6.1.4 Setf expanders

Setf Expander: (setf agent-elt) (index array-agent) ¶

Package

sento.agent.array.

Source

array-agent.lisp.

Reader

agent-elt (function).

Writer

agent-set (function).

Setf Expander: (setf agent-gethash) (key hash-agent) ¶

Package

sento.agent.hash.

Source

hash-agent.lisp.

Reader

agent-gethash (function).

Writer

agent-puthash (function).

---

6.1.5 Ordinary functions

Function: add-routee (router routee) ¶

Adds a routee/actor to the router.

Package

sento.router.

Source

router.lisp.

Function: agent-clrhash (hash-agent) ¶

Clears the hash-table. See ‘cl:clrhash‘.

Package

sento.agent.hash.

Source

hash-agent.lisp.

Function: agent-delete (item array-agent &rest delete-args) ¶

Deletes item from array. Internally uses ‘delete‘. Returns ‘T‘.

- ‘item‘: the item to delete.
- ‘array-agent‘: the array agent instance.
- ‘delete-args‘: any arguments passed on to ‘delete‘.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: agent-doarray (fun array-agent) ¶

’Do’ arbitrary atomic operation on the array.

- ‘fun‘: is a 1-arity function taking the array. This function can operate on the array without interference from other threads. The result of this function must be an array which will be the new agent state. - ‘array-agent‘: is the ‘array-agent‘ instance.

The result of ‘agent-doarray‘ is ‘T‘.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: agent-dohash (fun hash-agent) ¶

’Do’ arbitrary atomic operation on the hash-table.

- ‘fun‘: is a 1-arity function taking the hash-table. This function can operate on the hash-table without interference from other threads. The result of this function must be a hash-table. - ‘hash-agent‘: is the ‘hash-agent‘ instance.

The result of ‘agent-dohash‘ is ‘T‘.

Package

sento.agent.hash.

Source

hash-agent.lisp.

Function: agent-elt (index array-agent) ¶

Retrieves the value of the specified index of the array. ‘agent-elt‘ allows ‘setf‘ing like:

“‘
(setf (agent-elt 0 cut) 11)
“‘

- ‘index‘: the index to retrieve.
- ‘array-agent‘: the array agent instance.

In case of error ‘agent-elt‘ returns the error condition that ‘elt‘ raises.

The ‘setf‘ functionality will call ‘err-fun‘ on error if it has been configured.

Package

sento.agent.array.

Source

array-agent.lisp.

Setf expander for this function

(setf agent-elt).

Function: agent-get (agent get-fun) ¶

Gets the current state of the ‘agent‘.
‘get-fun‘ must accept one parameter. That is the current-state of the ‘agent‘. To return the current state ‘get-fun‘ may be just the ‘identity‘ function.

Package

sento.agent.

Source

agent.lisp.

Function: agent-get-quick (agent get-fun) ¶

Gets the current state with bypassing the messaging.
If you need consistent results this function should not be used.

Package

sento.agent.

Source

agent.lisp.

Function: agent-gethash (key hash-agent) ¶

Retrieves value from hash-table, or ‘nil‘ if it doesn’t exist.
See ‘cl:gethash‘ for more info.

This supports setting a hash using ‘setf‘ in the same way as with ‘cl:hash-table‘.

Returns any raised condition or the value from ‘gethash‘.

Package

sento.agent.hash.

Source

hash-agent.lisp.

Setf expander for this function

(setf agent-gethash).

Function: agent-pop (array-agent) ¶

Pops from array and returns the popped value. Internally uses ‘vector-pop‘, so the array must have a ‘fill-pointer‘. In case of error from using ‘vector-pop‘ the condition is returned.

- ‘array-agent‘: the array agent instance.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: agent-push (item array-agent) ¶

Pushes a value to the array/vector. Internally uses ‘vector-push-extend‘, so the array must have a ‘fill-pointer‘.

‘item‘: item to push.
‘array-agent‘: the array agent instance.

On error it will call ‘err-fun‘ with the raised condition, if ‘err-fun‘ has been configured.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: agent-push-and-getidx (item array-agent) ¶

Pushes ‘item‘ to the array. This function is similar to ‘agent-push‘ but returns the index of the pushed value similar as ‘vector-push‘ does. Therefore it is based on the somewhat slower ‘ask-s‘ actor pattern. So if you don’t care about the new index of the pushed item use ‘agent-push‘ instead. But this one is able to immediately return error conditions that may occur on ‘vector-push‘.

- ‘item‘: item to push.
- ‘array-agent‘: the array agent instance.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: agent-remhash (key hash-agent) ¶

Delete a hash-table entry. See ‘cl:remhash‘. Returns ‘T‘ if entry existed, ‘NIL‘ otherwise.

Package

sento.agent.hash.

Source

hash-agent.lisp.

Function: agent-stop (agent) ¶

Stops the message handling of the agent.

Package

sento.agent.

Source

agent.lisp.

Function: agent-update (agent update-fun) ¶

Updates the ‘agent‘ state.

‘update-fun‘ must accept one parameter. That is the current state of the ‘agent‘. The return value of ‘update-fun‘ will be taken as the new state of the ‘agent‘.

Package

sento.agent.

Source

agent.lisp.

Function: agent-update-and-get (agent update-fun) ¶

Updates the ‘agent‘ state.

‘update-fun‘ must accept one parameter. That is the current state of the ‘agent‘. The return value of ‘update-fun‘ will be taken as the new state of the ‘agent‘. This function makes the update and returns the new value.

Package

sento.agent.

Source

agent.lisp.

Function: assert-cond (assert-fun max-time &optional sleep-time) ¶

Obsolete, use ‘await-cond’ instead.

Package

sento.miscutils.

Source

miscutils.lisp.

Function: call (actor-cell message &key time-out) ¶

Send a message to a actor-cell instance and wait for a result.
Specify a timeout in seconds if you require a result within a certain period of time.
Be aware though that this is a resource intensive wait based on a waiting thread.
The result can be of different types.
Normal result: the last expression of ‘handle-call‘ (or ‘receive‘ in ‘act:actor‘) implementation. Error result: ‘(cons :handler-error <condition>)’
In case of time-out the error condition is a bt2:timeout.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Function: cancel (wheel-timer sig) ¶

Cancels a timer with the given signature ‘sig‘.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

Function: cast (actor-cell message &optional sender) ¶

Sends a message to a actor-cell asynchronously. There is no result. If a ‘sender’ is specified the result will be sent to the sender.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Function: collect-backtrace (condition) ¶

Package

sento.miscutils.

Source

miscutils.lisp.

Function: complete-p (future) ¶

Is ‘future‘ completed? Returns either ‘t‘ or ‘nil‘.

Package

sento.future.

Source

fcomputation.lisp.

Function: config-from (config-string) ¶

Parses the given config-string, represented by common lisp s-expressions. The config is composed of plists in a hierarchy.

This function parses (run through ‘cl:read‘) the given config string. The config string can be generated by:

“‘
(let ((*print-case* :downcase))
(prin1-to-string ’(defconfig
(:foo 1
:bar 2))))
“‘
Or just be given by reading from a file.
Notice the ’config’ s-expr must start with the root ‘car‘ ’defconfig’.

Package

sento.config.

Source

config.lisp.

Function: error-p (future) ¶

Is ‘future‘ errored? Returns either ‘t‘ or ‘nil‘.

Package

sento.future.

Source

fcomputation.lisp.

Function: fawait (fut &key timeout sleep-time) ¶

Wait for the future ‘FUT‘ to be ready. Returns ‘VALUES‘ with ‘result’ of the future and ‘FUT’.
If the future is not ready after ‘TIMEOUT‘ seconds the ‘result’ is ‘NIL’.
The ‘SLEEP-TIME‘ parameter specifies the time to sleep between checks of the future.
The wait is based on attempts. To be accurate in terms of ‘TIMEOUT‘ the ‘SLEEP-TIME‘ should be a divisor of ‘TIMEOUT‘. Disclaimer: naive implementation. There may be better solutions.

Package

sento.future.

Source

fcomputation.lisp.

Function: filter (fun lst) ¶

Package

sento.miscutils.

Source

miscutils.lisp.

Function: fresult (future) ¶

Get the computation result. If not yet available ‘:not-ready‘ is returned.

Package

sento.future.

Source

fcomputation.lisp.

Function: futurep (object) ¶

Checks if type of ‘object‘ is ‘future‘.

Package

sento.future.

Source

fcomputation.lisp.

Function: get-current-millis () ¶

Package

sento.timeutils.

Source

timeutils.lisp.

Function: has-stashed-messages-p (stashing) ¶

Are there any stashed messages?

Package

sento.stash.

Source

stash.lisp.

Function: make-actor-context (actor-system &optional id) ¶

Creates an ‘actor-context‘. Requires a reference to ‘actor-system‘ ‘id‘ is an optional value that can identify the ‘actor-context‘. Creating an actor-context manually is usually not needed.
An ‘asys:actor-system‘ implements the ‘actor-context‘ protocol. An ‘act:actor‘ contains an ‘actor-context‘.

Package

sento.actor-context.

Source

actor-context.lisp.

Function: make-actor-system (&optional config) ¶

Creates an ‘actor-system‘.

Allows to provide an optional configuration. See ‘asys:*default-config*‘. If no config is provided the default config is used.
Is a config provided then it is merged with the default config. Config options in the existing config override the default config. See ‘config:config-from‘.

Package

sento.actor-system.

Source

actor-system.lisp.

Function: make-agent (state-fun &optional actor-context dispatcher-id) ¶

Makes a new ‘agent‘ instance.

- ‘state-fun‘ is a function that takes no parameter and provides the initial state of the ‘agent‘ as return value.
- ‘actor-context‘: optionally specify an ‘asys:actor-system‘ as ‘ac:actor-context‘. If specified the agent will be registered in the system and destroyed with it should the ‘asys:actor-system‘ be destroyed. In addition the agent will use the systems shared message dispatcher and will _not_ create it’s own. - ‘dispatcher-id‘: the dispatcher is configurable. Default is ‘:shared‘. But you may use also ‘:pinned‘ or a custom configured one. Be aware that ‘:shared‘ of a custom dispatcher only works if an ‘actor-context‘ was specified.

Package

sento.agent.

Source

agent.lisp.

Function: make-array-agent (context &key initial-array error-fun dispatcher-id) ¶

Creates an agent that wraps a CL array/vector.

- ‘context‘: something implementing ‘ac:actor-context‘ protocol like ‘asys:actor-system‘. Specifying ‘nil‘ here creates an agent outside of an actor system. The user has to take care of that himself. - ‘initial-array‘: specify an initial array/vector.
- ‘error-fun‘: a 1-arrity function taking a condition that was raised.
Use this to get notified of error when using the update functions of the agent.
- ‘dispatcher-id‘: a dispatcher. defaults to ‘:shared‘.

Package

sento.agent.array.

Source

array-agent.lisp.

Function: make-atomic-integer (&key value) ¶

Package

sento.atomic.

Source

atomic.lisp.

Function: make-atomic-reference (&key value) ¶

Package

sento.atomic.

Source

atomic.lisp.

Function: make-dispatcher (actor-context identifier &rest config) ¶

Default constructor.
This creates a ‘disp:shared-dispatcher‘ with the given dispatcher config, see ‘asys:*default-config*‘. Each worker is based on a ‘:pinned‘ actor meaning that it has its own thread.
Specify an ‘ac:actor-context‘ where actors needed in the dispatcher are created in.

Package

sento.dispatcher.

Source

dispatcher.lisp.

Function: make-dispatcher-worker (num actor-context dispatcher-ident) ¶

Constructor for creating a worker.
‘num‘ only has the purpose to give the worker a name which includes a number. ‘dispatcher-ident is the dispatcher identifier.

Package

sento.dispatcher.

Source

dispatcher.lisp.

Function: make-eventstream (actor-context &rest config) ¶

Creating an eventstream is done by the ‘asys:actor-system‘ which is then available system wide.
But in theory it can be created individually by just passing an ‘ac:actor-context‘ (though I don’t know what would be the reason to create an eventstream for the context of a single actor. Maybe to address only a certain hierarchy in the actor tree.)

- ‘actor-context‘: the ‘ac:actor-context‘ where the eventstream actor should be created in.
- ‘config‘: is a plist with the ‘:dispatcher-id‘ key and a dispatcher id as value. Defaults to ‘:shared‘. This dispatcher type should be used by the actor.

Package

sento.eventstream.

Source

eventstream.lisp.

Function: make-fsm (actor-context &key name start-with event-handling type dispatcher-id) ¶

‘make-fsm‘ Function

Creates a finite state machine (FSM) within the given ‘actor-context‘.

**Parameters**

- ‘actor-context‘: Can be an actor, an actor-context (class), or an actor-system in which this FSM is created.

- ‘name‘: A string representing the name of the FSM. Must be a string.

- ‘start-with‘: A cons cell where the car is the initial state and the cdr is the initial data for the FSM. Must be a cons.

- ‘event-handling‘: An optional function for handling events. It can be ‘nil‘ if not provided. Must be either a function or ‘nil‘. If omitted, the FSM will effectively do nothing. The function body should be constructed using the provided FSM-related macros such as ‘on-event‘ and ‘on-transition‘.

- ‘type‘: The type of actor to create. Defaults to ‘’fsm‘.

- ‘dispatcher-id‘: Identifies the dispatcher for the FSM. Defaults to ‘:shared‘.

**Description**

The ‘make-fsm‘ function initializes an FSM actor with a specified initial state and associated data. The FSM’s behavior is defined by the ‘event-handling‘ function, which processes events if provided. This function should utilize the provided macros like ‘on-event‘ and ‘on-transition‘ to structure its body, enabling robust event handling and state transition management. Without this function, the FSM will not perform any actions.

This function configures the FSM within the given ‘actor-context‘, ensuring it is properly set up according to the parameters specified through the ‘ac:actor-of‘ function.

Package

sento.fsm.

Source

fsm.lisp.

Function: make-future (execute-fun) ¶

Creates a future. ‘execute-fun‘ is the lambda that is executed when the future is created.
‘execute-fun‘ takes a parameter which is the ‘execute-fun‘ funtion. ‘execute-fun‘ function
takes the ‘promise‘ as parameter which is the computed value. Calling ‘execute-fun‘ with the promise
will fulfill the ‘future‘.
Manually calling ‘execute-fun‘ to fulfill the ‘future‘ is in contrast to just fulfill the ‘future‘ from a return value. The benefit of the ‘execute-fun‘ is flexibility. In a multi-threaded environment ‘execute-fun‘ could spawn a thread, in which case ‘execute-fun‘ would return immediately but no promise-value can be given at that time. The ‘execute-fun‘ can be called from a thread and provide the promise.

Create a future with:

“‘elisp
(make-future (lambda (execute-fun)
(let ((promise (delayed-computation)))
(bt2:make-thread (lambda ()
(sleep 0.5)
(funcall execute-fun promise))))))
“‘

Package

sento.future.

Source

fcomputation.lisp.

Function: make-hash-agent (context &key initial-hash-table error-fun dispatcher-id) ¶

Creates an agent that wraps a CL hash-table.

- ‘context‘: something implementing ‘ac:actor-context‘ protocol like ‘asys:actor-system‘. Specifying ‘nil‘ here creates an agent outside of an actor system. The user has to take care of that himself. - ‘initial-hash-table‘: specify an initial hash-table.
- ‘error-fun‘: a 1-arrity function taking a condition that was raised.
Use this to get notified of error when using the update functions of the agent.
- ‘dispatcher-id‘: a dispatcher. defaults to ‘:shared‘.

Package

sento.agent.hash.

Source

hash-agent.lisp.

Function: make-model (&key object err-fun) ¶

Package

sento.agent.usecase-commons.

Source

agent-usecase-commons.lisp.

Function: make-router (&key strategy routees) ¶

Default constructor of router.
Built-in strategies: ‘:random‘, ‘:round-robin‘.
Specify your own strategy by providing a function that takes a ‘fixnum‘ as parameter which represents the number of routees and returns a ‘fixnum‘ that represents the index of the routee to choose.

Specify ‘routees‘ if you know them upfront.

Package

sento.router.

Source

router.lisp.

Function: make-timer (delay run-fun) ¶

Package

sento.timeutils.

Source

timeutils.lisp.

Function: make-wheel-timer (&rest config) ¶

Creates a new ‘wt:wheel-timer‘.

‘config‘ is a parameter for a list of key parameters including:

- ‘:resolution‘ the timer time resolution in milliseconds. 100 milliseconds is a good default.
- ‘:max-size‘ the number of timer slots this wheel should have.

Note that an ‘asys:actor-system‘ includes an instance as ‘asys:scheduler‘ that can be used within actors. But you can also create your own instance.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

Function: merge-config (config fallback-config) ¶

Merges config.
‘config‘ specifies a config that overrides what exists in ‘fallback-config‘.
‘fallback-config‘ is a default. If something doesn’t exist in ‘config‘ it is taken from ‘fallback-config‘. Both ‘config‘ and ‘fallback-config‘ must be plists, or a ’config’ that was the output of ‘config-from‘.

Package

sento.config.

Source

config.lisp.

Function: mkstr (&rest args) ¶

Converts all parameters to string and concatenates them.

Package

sento.miscutils.

Source

miscutils.lisp.

Reader: model-err-fun (instance) ¶

Writer: (setf model-err-fun) (instance) ¶

Package

sento.agent.usecase-commons.

Source

agent-usecase-commons.lisp.

Target Slot

err-fun.

Reader: model-object (instance) ¶

Writer: (setf model-object) (instance) ¶

Package

sento.agent.usecase-commons.

Source

agent-usecase-commons.lisp.

Target Slot

object.

Function: register-dispatcher (system dispatcher) ¶

Registers a dispatcher to the actor-system.

- ‘system‘: the actor-system
- ‘dispatcher‘: the dispatcher instance.

Package

sento.actor-system.

Source

actor-system.lisp.

Function: register-new-dispatcher (system dispatcher-id &key workers strategy) ¶

Makes and registers a new dispatcher.

- ‘system‘: the actor-system
- ‘dispatcher-id‘: the dispatcher identifier. Usually a global symbol like ‘:foo‘ - ‘:workers‘: key argument for the number of workers.
- ‘:strategy‘: key argument for the dispatcher strategy (:random or :round-robin)

Package

sento.actor-system.

Source

actor-system.lisp.

Function: reply (msg &optional sender) ¶

Replies to a sender. Sender must exist.
Use this from within receive function to reply to a sender.

Package

sento.actor.

Source

actor.lisp.

Function: retrieve-keys (config) ¶

Retrieves all section keys

Package

sento.config.

Source

config.lisp.

Function: retrieve-section (config section) ¶

Retrieves the given named section which should be a (global) ‘symbol‘ (a key). A section usually is a plist with additional configs or sub sections.
This function looks only in the root hierarchy of the given config.

Package

sento.config.

Source

config.lisp.

Function: retrieve-value (section key) ¶

Retrieves the value for the given key and section.

Package

sento.config.

Source

config.lisp.

Function: routees (router) ¶

Returns the routees as list.

Package

sento.router.

Source

router.lisp.

Function: running-p (actor-cell) ¶

Returns true if this server is running. ‘nil‘ otherwise.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Function: schedule-once (wheel-timer delay timer-fun &key sig reuse-sig) ¶

Schedule a function execution once:

- ‘wheel-timer‘ is the ‘wt:wheel-timer‘ instance.
- ‘delay‘ is the number of seconds (float) delay when ‘timer-fun‘ should be executed.
- ‘timer-fun‘ is a 0-arity function that is executed after ‘delay‘. BEWARE: the function is executed in the timer thread. Make sure that you off-load long running tasks to other threads, or to a custom dispatcher (i.e. ‘tasks‘). - ‘sig‘ is an optional symbol or string that is used to identify the timer and is used for ‘cancel‘.
- ‘reuse-sig‘ is a boolean that indicates whether the signature should be cleaned up after the timer has been executed.

Returns: signature (symbol) that represents the timer and can be used to cancel the timer.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

Function: schedule-recurring (wheel-timer initial-delay delay timer-fun &optional sig) ¶

Schedule a recurring function execution:

- ‘wheel-timer‘ is the ‘wt:wheel-timer‘ instance.
- ‘initial-delay‘ is the number of seconds (float) delay when ‘timer-fun‘ is executed the first time.
- ‘delay‘ is the number of seconds (float) delay when ‘timer-fun‘ should be executed.
- ‘timer-fun‘ is a 0-arity function that is executed after ‘delay‘. BEWARE: the function is executed in the timer thread. Make sure that you off-load long running tasks to other threads, or to a custom dispatcher (i.e. ‘tasks‘). - ‘sig‘ is an optional symbol or string that is used to identify the timer and is used for ‘cancel-recurring‘.

Returns the signature that was either passed in via ‘sig‘ or a generated one.
The signature can be used to cancel the timer via ‘cancel-recurring‘.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

Function: shutdown-wheel-timer (wheel-timer) ¶

Shuts down the wheel timer and free resources.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

Function: stash (msg) ¶

Stash ‘msg‘ for later unstash.
On stashing a message the actor should respond with: ‘(cons :no-reply state)‘ to avoid returning a response to sender (if given).

This function is expected to be run from within ’receive’ function.

Package

sento.stash.

Source

stash.lisp.

Function: stop (router) ¶

Stops all routees.

Package

sento.router.

Source

router.lisp.

Function: task-async (fun &key on-complete-fun) ¶

‘task-async‘ schedules the function ‘fun‘ for asynchronous execution.
‘fun‘ must be a 0-arity function.
‘on-complete-fun‘ is a 1-arity completion handler function. When called the result is delivered.
The completion handler function parameter may also be a ‘(cons :handler-error condition)‘ construct in case an error happened within the message handling.

Be aware about the execution of the completion function:
The completion function is, by a very high chance, executed by the thread that executed ‘fun‘ function.
Only in very rare cases it could be possible that the completion function is executed by the caller of ‘task-async‘. See ‘future:fcompleted‘ for more info.

Using ‘task-async‘ provides two alternatives:

- together with ‘task-await‘
- or with completion handler

In fact it is possible to call ‘task-await‘ as well, but then you probably don’t need a completion handler.
Using the completion handler makes the processing complete asynchronous.

The result of ‘task-async‘ is a ‘task‘.
Store this ‘task‘ for a call to ‘task-async‘ (even with or without using ‘on-complete-fun‘).
When _not_ using ‘on-complete-fun‘ users must call either ‘task-await‘ or ‘task-shutdown‘ for the task to be cleaned up.
When using ‘on-complete-fun‘ this is done for you.

Example:

“‘elisp
;; create actor-system
(defparameter *sys* (make-actor-system))

(with-context (*sys*)
(let ((x (task-async (lambda () (some bigger computation))))
(y 1))
(+ (task-await x) y)))

;; use-case with ‘on-complete-fun‘
(defun my-task-completion (result)
(do-something-with result))

(with-context (*sys*)
(task-async (lambda () (some-bigger-computation))
:on-complete-fun #’my-task-completion))
“‘

Package

sento.tasks.

Source

tasks.lisp.

Function: task-async-stream (fun lst) ¶

‘task-async-stream‘ concurrently applies ‘fun‘ on all elements of ‘lst‘.
‘fun‘ must be a one-arity function taking an element of ‘lst‘.

The concurrency depends on the number of available ‘:shared‘ dispatcher workers.
Each element of ‘lst‘ is processed by a worker of the ‘asys:actor-system‘s ‘:shared‘ dispatcher. If all workers are busy then the computation of ‘fun‘ is queued.

Example:

“‘elisp
;; create actor-system
(defparameter *sys* (make-actor-system))

(with-context (*sys*)
(->>
’(1 2 3 4 5)
(task-async-stream #’1+)
(reduce #’+)))

=> 20 (5 bits, #x14, #o24, #b10100)
“‘

Package

sento.tasks.

Source

tasks.lisp.

Function: task-await (task &optional time-out) ¶

‘task-await‘ waits (by blocking) until a result has been generated for a previous ‘task-async‘ by passing the ‘task‘ result of ‘task-async‘ to ‘task-await‘. Specify ‘time-out‘ in seconds. If ‘task-await‘ times out a ‘(cons :handler-error ’ask-timeout)‘ will be returned.
‘task-await‘ also stops the ‘task‘ that is the result of ‘task-async‘, so it is of no further use.

Package

sento.tasks.

Source

tasks.lisp.

Function: task-shutdown (task) ¶

‘task-shutdown‘ shuts down a task in order to clean up resources.

Package

sento.tasks.

Source

tasks.lisp.

Function: task-start (fun) ¶

‘task-start‘ runs the given function ‘fun‘ asynchronously.
‘fun‘ must be a 0-arity function.
Use this if you don’t care about any response or result, i.e. for I/O side-effects.
It returns ‘(values :ok <task>)‘. ‘<task> is in fact an actor given back as reference.
The task is automatically stopped and removed from the context and will not be able to handle requests.

Package

sento.tasks.

Source

tasks.lisp.

Function: task-yield (fun &optional time-out) ¶

‘task-yield‘ runs the given function ‘fun‘ by blocking and waiting for a response from the ‘task‘, or until the given timeout was elapsed. ‘fun‘ must be a 0-arity function.

A normal response from the actor is passed back as the response value.
If the timeout elapsed the response is: ‘(values :handler-error miscutils:ask-timeout)‘.

Example:

“‘elisp
;; create actor-system
(defparameter *sys* (make-actor-system))

(with-context (*sys*)
(task-yield (lambda () (+ 1 1))))

=> 2 (2 bits, #x2, #o2, #b10)
“‘

Package

sento.tasks.

Source

tasks.lisp.

Function: unstash-all () ¶

Unstash all messages.
Messages are re-submitted to the actor in the order they were stashed.
Resubmitting means they are added to the end of the queue like any ordinary message would.

This function is expected to be run from within ’receive’ function.

Package

sento.stash.

Source

stash.lisp.

Function: wait-cond (cond-fun &optional sleep-time max-time) ¶

Waits until ‘cond-fun’ is not ‘nil’ or ‘max-time’ elapsed. This blocks the calling thread.

Package

sento.timeutils.

Source

timeutils.lisp.

---