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-get (generic function).
• atomic-swap (generic function).

Internals

atomic-cas (generic function).

---

4.1.3 sento/src/atomic/atomic.lisp

Source

sento.asd.

Parent Component

atomic (module).

Public Interface

• 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-cas (method).
• atomic-cas (method).
• 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 (function).
• shutdown-wheel-timer (function).
• wheel-timer (class).

Internals

• 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).
• 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/dispatcher-api.lisp

Dependency

miscutils.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.9 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-unbounded (class).

Internals

queue-base (class).

---

4.1.10 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

• %triggered-stop-fun (function).
• 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.11 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.12 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).
• other-init-args (reader method).
• 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.13 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.14 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.15 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.16 sento/src/fcomputation.lisp

Dependency

actor-context-api.lisp (file).

Source

sento.asd.

Parent Component

src (module).

Packages

sento.future.

Public Interface

• complete-p (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.17 sento/src/actor.lisp

Dependency

fcomputation.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).
• 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.18 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.19 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.20 sento/src/tasks.lisp

Dependency

eventstream.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.21 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.22 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.23 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.24 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.25 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).
• shutdown (method).
• stop (method).
• subscribe (method).
• timeout-timer (reader method).
• unsubscribe (method).

Internals

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

---

4.1.26 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.27 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.28 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.29 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: *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: *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: fcompleted (future (result) &body body) ¶

Completion handler on the given ‘future‘.

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

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.

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: 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
(bt:make-thread
(lambda ()
(fresolve (do-some-lengthy-calculation)))))
“‘

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 bt:timeout.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Function: cancel (wheel-timer timer) ¶

Cancels a timer.
‘wheel-timer‘ is the ‘wt:wheel-timer‘ instance. ‘timer‘ is the timer object returned by ‘wt:schedule‘.

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: 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: 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-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)))
(bt: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 ‘wheel-timer‘.

‘config‘ is a parameter for a list of key parameters including: ‘:resolution‘: the timer time resolution in milliseconds. ‘:max-size‘: the maximum size of timer functions this wheel can handle.

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 (wheel-timer delay timer-fun) ¶

Schedule a function execution:

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

returns: a timer object that can be used to cancel the timer.

Package

sento.wheel-timer.

Source

wheel-timer.lisp.

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

Shuts down the wheel timer and frees 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.

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.

---

6.1.6 Generic functions

Generic Function: ! (actor message &optional sender) ¶

Sends a message to the ‘actor‘. ‘tell‘ is asynchronous.
‘tell‘ does not expect a result. If a ‘sender‘ is specified the receiver will be able to send a response.

Alternatively to the ‘tell‘ function one can equally use the ‘!‘ function designator.

Package

sento.actor.

Alias for

tell.

Generic Function: ? (actor message &key time-out) ¶

Sends a message to the ‘actor‘. A ‘future‘ is returned.
Specify ‘timeout‘ if a message is to be expected after a certain time.
An ‘:handler-error‘ with ‘timeout‘ condition will be returned is the call timed out.

An ‘ask‘ is similar to a ‘ask-s‘ in that the caller gets back a result
but it doesn’t have to actively wait for it. Instead a ‘future‘ wraps the result.
However, the internal message handling is based on ‘tell‘.
How this works is that the message to the target ‘actor‘ is not ’sent’ using the callers thread but instead an anonymous ‘actor‘ is started behind the scenes. This anonymous actor can weit for a response from the target actor. The response then fulfills the future.

Alternatively to the ‘ask‘ function one can equally use the ‘?‘ function designator.

Package

sento.actor.

Alias for

ask.

Generic Function: actor-of (context &key receive init destroy dispatcher state type name other-args) ¶

Interface for creating an actor.

**!!! Attention:** this factory function wraps the ‘act:make-actor‘ functionality to something more simple to use.
Using this function there is no need to use both ‘act:make-actor‘.

‘context‘ is either an ‘asys:actor-system‘, an ‘ac:actor-context‘, or an ‘act:actor‘ (any type of actor).
The new actor is created in the given context.

- ‘:receive‘ is required and must be a 3-arity lambda with arguments: 1. the actor, 2. the message, 3. the state
Usually expressed as ‘(lambda (self msg state))‘.
- ‘:init‘: is an optional initialization function with one argument: the actor instance (self).
This represents a ’start’ hook that is called after the actor was fully initialized.
- ‘:destroy‘: is an optional destroy function also with the actor instance as argument.
This function allows to unsubsribe from event-stream or such.
- ‘:state‘ key can be used to initialize with a state.
- ‘:dispatcher‘ key can be used to define the message dispatcher manually.
Options are ‘:shared‘ (default) and ‘:pinned‘.
- ‘:type‘ can specify a custom actor class. See ‘act:make-actor‘ for more info.
- ‘:name‘ to set a specific name to the actor, otherwise a random name will be used.
- ‘:other-args‘ are in the actor instance as ‘other-init-args‘ and can be acted upon in i.e. ‘pre-start‘ for additional initialization.

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: actor-of ((system actor-system) &key receive init destroy dispatcher state type name other-args) ¶

See ‘ac:actor-of‘

Source

actor-system.lisp.

Method: actor-of ((context actor-context) &key receive init destroy dispatcher state type name other-args) ¶

See ‘ac:actor-of‘.

Source

actor-context.lisp.

Method: actor-of ((actor actor) &key receive init destroy dispatcher state type name other-args) ¶

‘ac:actor-context‘ protocol implementation

Source

actor.lisp.

Generic Function: after-stop (actor) ¶

Generic function definition that is called after the actor has stopped, that is after the message box is stopped. No more messages are being processed.

Under normal circumstances one would provide an ‘destroy‘ function at construction of the actor instead (see above). This generic function is more meant to create specialized actors by providing different implementations.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: after-stop ((self actor)) ¶

Source

actor.lisp.

Generic Function: all-actors (context) ¶

Retrieves all actors of this context as a list

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: all-actors ((self actor-system)) ¶

See ‘ac:all-actors‘

Source

actor-system.lisp.

Method: all-actors ((context actor-context)) ¶

See ‘ac:all-actors‘

Source

actor-context.lisp.

Method: all-actors ((actor actor)) ¶

‘ac:actor-context‘ protocol implementation.

Source

actor.lisp.

Generic Function: ask (actor message &key time-out) ¶

Sends a message to the ‘actor‘. A ‘future‘ is returned.
Specify ‘timeout‘ if a message is to be expected after a certain time.
An ‘:handler-error‘ with ‘timeout‘ condition will be returned is the call timed out.

An ‘ask‘ is similar to a ‘ask-s‘ in that the caller gets back a result
but it doesn’t have to actively wait for it. Instead a ‘future‘ wraps the result.
However, the internal message handling is based on ‘tell‘.
How this works is that the message to the target ‘actor‘ is not ’sent’ using the callers thread but instead an anonymous ‘actor‘ is started behind the scenes. This anonymous actor can weit for a response from the target actor. The response then fulfills the future.

Alternatively to the ‘ask‘ function one can equally use the ‘?‘ function designator.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: ask ((self router) message &key time-out) ¶

Posts the message to one routee. The routee is chosen from the router ‘strategy‘. Otherwise see: ‘act:ask‘.

Source

router.lisp.

Method: ask ((self actor) message &key time-out) ¶

Source

actor.lisp.

Generic Function: ask-s (actor message &key time-out) ¶

Sends a message to the ‘actor‘. ‘ask-s‘ is synchronous and waits for a result.
Specify ‘timeout‘ if a message is to be expected after a certain time.
An ‘:handler-error‘ with ‘timeout‘ condition will be returned if the call timed out.

‘ask-s‘ assumes, no matter if ‘ask-s‘ is issued from outside or inside an actor, that the response is delivered back to the caller. That’s why ‘ask-s‘ does block the execution until the result is available. The ‘receive‘ function return value will be used as the result of ‘receive‘.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: ask-s ((self router) message &key time-out) ¶

Posts the message to one routee. The routee is chosen from the router ‘strategy‘. Otherwise see: ‘act:ask-s‘.

Source

router.lisp.

Method: ask-s ((self actor) message &key time-out) ¶

Source

actor.lisp.

Generic Function: atomic-get (atomic) ¶

Retrieve value from atomic object.

Package

sento.atomic.

Source

atomic-api.lisp.

Methods

Method: atomic-get ((int atomic-integer)) ¶

Source

atomic.lisp.

Method: atomic-get ((ref atomic-reference)) ¶

Source

atomic.lisp.

Generic Function: atomic-swap (atomic fn &rest args) ¶

Update the the atomic object to the value returned by calling function ‘fn‘ with the previous value of the atomic object and ‘args‘.

Package

sento.atomic.

Source

atomic-api.lisp.

Methods

Method: atomic-swap ((int atomic-integer) fn &rest args) ¶

Source

atomic.lisp.

Method: atomic-swap ((ref atomic-reference) fn &rest args) ¶

Updates the cell value of REF atomically to the value returned by calling function FN with ARGS and the previous cell value of REF. The first argument of FN should be the previous cell value of REF.

Source

atomic.lisp.

Generic Function: become (new-behavior) ¶

Changes the receive of the actor to the given ‘new-behavior‘ function.
The ‘new-behavior‘ function must accept 3 parameters: the actor instance, the message and the current state. This function should be called from within the behavior receive function.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: become (new-behavior) ¶

Source

actor.lisp.

Generic Reader: cause (condition) ¶

Package

sento.timeutils.

Methods

Reader Method: cause ((condition ask-timeout)) ¶

Source

timeutils.lisp.

Target Slot

cause.

Generic Reader: context (actor) ¶

This is the ‘actor-context‘ every actor is composed of.
When the actor is created from scratch it has no ‘actor-context‘.
When created through the ‘actor-context‘s, or system’s ‘actor-of‘ function an ‘actor-context‘ will be set.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Reader Method: context ((actor actor)) ¶

The ‘ac:actor-context‘

Target Slot

context.

Generic Writer: (setf context) (object) ¶

Package

sento.actor.

Methods

Writer Method: (setf context) ((actor actor)) ¶

The ‘ac:actor-context‘

Source

actor-api.lisp.

Target Slot

context.

Generic Function: dispatch (dispatcher dispatcher-exec-fun) ¶

Dispatches a function (‘dispatch-exec-fun‘) to a worker of the dispatcher to execute there. ‘dispatch‘ does a ‘ask-s‘ to a ‘dispatcher‘ worker, which means this call will block.

Package

sento.dispatcher.

Source

dispatcher-api.lisp.

Methods

Method: dispatch ((self shared-dispatcher) dispatch-exec-fun-args) ¶

Source

dispatcher.lisp.

Generic Function: dispatch-async (dispatcher dispatcher-exec-fun) ¶

Dispatches a function to a worker of the dispatcher to execute there. ‘dispatch-async‘ does a ‘tell‘ to a ‘dispatcher‘ worker and is asynchronous.

Package

sento.dispatcher.

Source

dispatcher-api.lisp.

Methods

Method: dispatch-async ((self shared-dispatcher) dispatch-exec-fun-args) ¶

Source

dispatcher.lisp.

Generic Reader: dispatchers (object) ¶

Package

sento.actor-system.

Methods

Reader Method: dispatchers ((actor-system actor-system)) ¶

Internal API: contains a list of available message dispatchers.

Source

actor-system.lisp.

Target Slot

dispatchers.

Generic Function: emptyq-p (queue-base) ¶

Returns ‘T’ if there is no element in the queue.

Package

sento.queue.

Source

queue.lisp.

Methods

Method: emptyq-p ((self queue-bounded)) ¶

Method: emptyq-p ((self queue-unbounded)) ¶

Generic Reader: evstream (object) ¶

Package

sento.actor-system.

Methods

Reader Method: evstream ((actor-system actor-system)) ¶

The system event stream. See ‘ev:eventstream‘ for more info.

Source

actor-system.lisp.

Target Slot

eventstream.

Generic Function: find-actors (context path &key test key) ¶

Returns actors to be found by the criteria of:

- ‘context‘: an ‘AC:ACTOR-CONTEXT‘, or an ‘ACT:ACTOR‘ or an ‘ASYS:ACTOR-SYSTEM‘ as all three implement ‘find-actors‘.
- ‘path‘: a path designator to be found. This can be just an actor name, like ’foo’, then ‘find-actors‘ will only look in the given context for the actor. It can also be: ’foo/bar’, a relative path, in which case ‘find-actors‘ will traverse the path (here ’bar’ is a child of ’foo’) to the last context and will try to find the actor by name there, ’bar’ in this case. Also possible is a root path like ’/user/foo/bar’ which will start traversing contexts started from the root context, which is the actor-system. - ‘test‘: a 2-arity test function where the 1st argument is the ‘path‘, the 2nd is the a result of the ‘key‘ function (which defaults to ‘ACT-CELL:NAME‘, so the name of the actor). The default function for ‘test‘ is ‘STRING=‘. However, in case of a multi-subpath ‘path‘ both ‘test‘ and ‘key‘ only apply to the last path component, which designates the actor name to be found.
- ‘key‘: a 1-arity function applied on an actor instance. Defaults to ‘ACT-CELL:NAME‘.

Depending on ‘test‘ function the last path component can be used as a wildcard when using a ‘test‘ function like ‘STR:STARTS-WITH-P‘ or ‘STR:CONTAINSP‘ for example.

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: find-actors ((self actor-system) path &key test key) ¶

See ‘ac:find-actors‘

Source

actor-system.lisp.

Method: find-actors ((context actor-context) path &key test key) ¶

See ‘ac:find-actors‘

Source

actor-context.lisp.

Method: find-actors ((actor actor) path &key test key) ¶

‘ac:actor-context‘ protocol implementation.

Source

actor.lisp.

Generic Function: handle-call (actor-cell message) ¶

Handles calls to the server. Must be implemented by subclasses.
The result of the last expression of this function is returned back to the ’caller’. State of the cell can be changed via ‘setf‘ing ‘*state*‘ variable.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Methods

Method: handle-call ((self actor) message) ¶

Source

actor.lisp.

Generic Function: handle-cast (actor-cell message) ¶

Handles casts to the server. Must be implemented by subclasses. State of the cell can be changed via ‘setf‘ing ‘*state*‘ variable.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Methods

Method: handle-cast ((self actor) message) ¶

Source

actor.lisp.

Generic Reader: id (object) ¶

Package

sento.actor-context.

Methods

Reader Method: id ((actor-context actor-context)) ¶

The id of this actor-context. Usually a string.

Source

actor-context.lisp.

Target Slot

id.

Generic Reader: identifier (object) ¶

Package

sento.dispatcher.

Methods

Reader Method: identifier ((dispatcher-base dispatcher-base)) ¶

Returns the identifier of the dispatcher.

Source

dispatcher.lisp.

Target Slot

identifier.

Generic Function: make-actor (receive &key name state type init destroy other-init-args) ¶

Constructs an ‘actor‘.

Arguments:

- ‘receive‘: message handling function taking one argument, the message.

- ‘name‘: give the actor a name. Must be unique within an ‘ac:actor-context‘.

- ‘type‘: Specify a custom actor class as the ‘:type‘ key. Defaults to ’actor.
Say you have a custom actor ‘custom-actor‘ and want ‘make-actor‘ create an instance of it. Then specify ‘:type ’custom-actor‘ on ‘make-actor‘ function.
If you have additional initializations to make you can do so in ‘initialize-instance‘.

- ‘state‘: initialize an actor with a state. (default is ‘nil‘)

- ‘init‘ and ‘destroy‘: are functions that take one argument, the actor instance.
Those hooks are called on (after) initialization and (after) stop respectively.

- ‘other-init-args‘: are additional arguments passed to ‘initialize-instance‘ of the actor class.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: make-actor (receive &key name state type init destroy other-init-args) ¶

Source

actor.lisp.

Generic Reader: msgbox (object) ¶

Generic Writer: (setf msgbox) (object) ¶

Package

sento.actor-cell.

Methods

Reader Method: msgbox ((actor-cell actor-cell)) ¶

Writer Method: (setf msgbox) ((actor-cell actor-cell)) ¶

The ‘message-box‘. By default the ‘actor‘/‘actor-cell‘ has no message-box.
When the actor is created through the ‘actor-context‘ of an actor, or the ‘actor-system‘ then it will be populated with a message-box.

Source

actor-cell.lisp.

Target Slot

msgbox.

Generic Reader: name (object) ¶

Package

sento.actor-cell.

Methods

Reader Method: name ((actor-cell actor-cell)) ¶

The name of the actor/actor-cell. If no name is specified a default one is applied.

Source

actor-cell.lisp.

Target Slot

name.

Generic Function: notify (context actor notification) ¶

Notify the ‘actor-context‘ about something that happened to an actor. Current exists:

- ‘:stopped‘: this will remove the actor from the context.

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: notify ((context actor-context) actor notification) ¶

Source

actor-context.lisp.

Generic Reader: other-init-args (object) ¶

Package

sento.actor.

Methods

Reader Method: other-init-args ((actor actor)) ¶

Other init args passed to ‘make-actor‘

Source

actor-api.lisp.

Target Slot

other-init-args.

Generic Function: path (actor) ¶

The path of the actor, including the actor itself.
The path denotes a tree which starts at the system context.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: path ((self actor)) ¶

Source

actor.lisp.

Generic Function: popq (queue-base) ¶

Pops the first element. Blocks until an element arrives.

Package

sento.queue.

Source

queue.lisp.

Methods

Method: popq ((self queue-bounded)) ¶

Method: popq ((self queue-unbounded)) ¶

Generic Function: pre-start (actor) ¶

Generic function definition called after initialization but before messages are accepted.
An ‘ac:actor-context‘ is available at this point as well as ‘act:*state*‘ variable definition.

Under normal circumstances one would provide an ‘init‘ function at construction of the actor instead (see above). This generic function is more meant to create specialized actors by providing different implementations.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: pre-start ((self actor)) ¶

Source

actor.lisp.

Generic Function: publish (eventstream message) ¶

Publish an event/message to the eventstream. Subscribers may receive notification if they registered for the right message pattern.

Package

sento.eventstream.

Source

eventstream-api.lisp.

Methods

Method: publish ((system actor-system) message) ¶

Convenience. Allows to publish to ‘ev:eventstream‘ by just providing the ‘asys:actor-system‘.

Source

actor-system.lisp.

Method: publish ((ev-stream eventstream) message) ¶

Publish to ‘ev:eventstream‘.

Source

eventstream.lisp.

Method: publish ((actor actor) message) ¶

Convenience. Allows to publish to ‘ev:eventstream‘ by just providing the actor.

Source

actor.lisp.

Generic Function: pushq (queue-base element) ¶

Pushes an element to the queue.

Package

sento.queue.

Source

queue.lisp.

Methods

Method: pushq ((self queue-bounded) element) ¶

Method: pushq ((self queue-unbounded) element) ¶

Generic Function: shutdown (context &key wait) ¶

Stops all actors in this context.
When the context is an ‘actor-context‘ this still stop the actor context and all its actors. For the ‘actor-system‘ it will stop the whole system with all actors.
Specify ‘wait‘ as ‘T‘ to block until all actors of the context are stopped (default ‘NIL‘).

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: shutdown ((self actor-system) &key wait) ¶

See ‘ac:shutdown‘

Source

actor-system.lisp.

Method: shutdown ((context actor-context) &key wait) ¶

See ‘ac:shutdown‘

Source

actor-context.lisp.

Generic Reader: state (object) ¶

Package

sento.actor-cell.

Methods

Reader Method: state ((actor-cell actor-cell)) ¶

The encapsulated state.

Source

actor-cell.lisp.

Target Slot

state.

Generic Function: stop (dispatcher) ¶

Stops the dispatcher. Stops all workers.

Package

sento.dispatcher.

Source

dispatcher-api.lisp.

Methods

Method: stop ((self shared-dispatcher)) ¶

Source

dispatcher.lisp.

Generic Function: stop (message-box-base &optional wait) ¶

Stops the message processing.
The message processing is not terminated while a message is still processed. Rather it is a graceful stop by waiting until a message has been processed. Provide ‘wait‘ EQ ‘T‘ to wait until the actor cell is stopped.

Package

sento.messageb.

Source

message-box.lisp.

Methods

Method: stop ((self message-box/dp) &optional wait) ¶

Method: stop ((self message-box/bt) &optional wait) ¶

Method: stop ((self message-box-base) &optional wait) ¶

Generic Function: stop (actor-cell &optional wait) ¶

Stops the actor-cells message processing gracefully.
This is not an immediate stop.
There are two ways to stop an actor (cell).

1. by calling this function.
It is not an immediate stop. The actor will finish the current message processing. ‘wait‘: waits until the cell is stopped.

2. by sending ‘:stop‘ to the actor (cell).
This won’t allow to wait when the actor is stopped, even not with ‘ask-s‘.
The ‘:stop‘ message (symbol) is normally processed by the actors message processing.

Package

sento.actor-cell.

Source

actor-cell.lisp.

Methods

Method: stop ((self actor) &optional wait) ¶

If this actor has an ‘actor-context‘, also stop all children.
In any case stop the actor-cell. See ‘actor-cell:stop‘ for more info on stopping.

Source

actor.lisp.

Method: stop ((self actor-cell) &optional wait) ¶

Generic Function: stop (context actor &key wait) ¶

Stops the given actor on the context.
The context may either be an ‘actor-context‘, or an ‘actor-system‘. The actor is then also removed from the context.
Specify ‘wait‘ as ‘T‘ to block until the actor is stopped (default ‘NIL‘).

Package

sento.actor-context.

Source

actor-context-api.lisp.

Methods

Method: stop ((self actor-system) actor &key wait) ¶

See ‘ac:stop‘

Source

actor-system.lisp.

Method: stop ((context actor-context) actor &key wait) ¶

See ‘ac:stop‘

Source

actor-context.lisp.

Generic Reader: strategy-fun (object) ¶

Package

sento.router.

Methods

Reader Method: strategy-fun ((router router)) ¶

The router strategy function.
The ‘strategy‘ is a function with a ‘fixnum‘ as input and a ‘fixnum‘ as output. The input represents the number of routees.
The output represents the index of the routee to choose by calling the function.

Source

router.lisp.

Target Slot

strategy-fun.

Generic Function: submit (message-box-base message withreply-p time-out handler-fun-args) ¶

Submit a message to the mailbox to be queued and handled.
‘handler-fun-args‘: list with first element the function designator and rest arguments.

Package

sento.messageb.

Source

message-box.lisp.

Methods

Method: submit ((self message-box/dp) message withreply-p time-out handler-fun-args) ¶

Submitting a message on a multi-threaded ‘dispatcher‘ is different as submitting on a single threaded message-box. On a single threaded message-box the order of message processing is guaranteed even when submitting from multiple threads. On the ‘dispatcher‘ this is not the case. The order cannot be guaranteed when messages are processed by different ‘dispatcher‘ threads. However, we still guarantee a ’single-threadedness’ regarding the state of the actor. This is achieved here by protecting the ‘handler-fun-args‘ execution with a lock.

The ‘time-out‘ with the ’dispatcher mailbox’ assumes that the message received the dispatcher queue
and the handler in a reasonable amount of time, so that the effective time-out applies on the actual
handling of the message on the dispatcher queue thread.

Returns the handler-result if ‘withreply-p’ is eq to ‘T’, otherwise the return is just ‘T’ and is usually ignored.

Method: submit ((self message-box/bt) message withreply-p time-out handler-fun-args) ¶

The ‘handler-fun-args‘ argument must contain a handler function as first list item. It will be apply’ed with the rest of the args when the message was ’popped’ from queue.

Generic Function: subscribe (eventstream subscriber &optional pattern) ¶

Subscribe to the eventstream to receive notifications of certain events or event types.

‘subscriber‘ must be an actor (or agent).

The ‘pattern‘ can be:

- nil: receive all events posted to the eventstream.
- a type, class type: this allows to get notifications when an instance of this type, or class type is posted.
I.e. if you want to listen to all string messages posted to the ev, thewn subscribe to ‘’string‘.
Or if you want to listen to all lists, subscribe with ‘’cons‘.
- a symbol or global symbol: if posted message is a symbol or global symbol then the symbols are compared (‘eq‘).
- a string: in which case an exact string comparison is made for a string message that is posted to the eventstream (‘string=‘).
- a list: if subscription if for a list structure, and the posted message is also a list structure, then a structure comparison (‘equalp‘) is made.

Package

sento.eventstream.

Source

eventstream-api.lisp.

Methods

Method: subscribe ((system actor-system) (subscriber actor) &optional pattern) ¶

Convenience. Allows to subscribe to ‘ev:eventstream‘ by just providing the ‘asys:actor-system‘.

Source

actor-system.lisp.

Method: subscribe ((ev-stream eventstream) (subscriber actor) &optional pattern) ¶

Subscribe to ‘ev:eventstream‘.

Source

eventstream.lisp.

Method: subscribe ((actor actor) (subscriber actor) &optional pattern) ¶

Convenience. Allows to subscribe to ‘ev:eventstream‘ by just providing the actor.

Source

actor.lisp.

Generic Reader: system (object) ¶

Package

sento.actor-context.

Methods

Reader Method: system ((actor-context actor-context)) ¶

A reference to the ‘actor-system‘.

Source

actor-context.lisp.

Target Slot

system.

Generic Function: tell (actor message &optional sender) ¶

Sends a message to the ‘actor‘. ‘tell‘ is asynchronous.
‘tell‘ does not expect a result. If a ‘sender‘ is specified the receiver will be able to send a response.

Alternatively to the ‘tell‘ function one can equally use the ‘!‘ function designator.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: tell ((self router) message &optional sender) ¶

Posts the message to one routee. The routee is chosen from the router ‘strategy‘. Otherwise see: ‘act:tell‘.

Source

router.lisp.

Method: tell ((self actor) message &optional sender) ¶

Source

actor.lisp.

Generic Reader: timeout-timer (object) ¶

Package

sento.actor-system.

Methods

Reader Method: timeout-timer ((actor-system actor-system)) ¶

A wheel-timer used for timeouts to make timeouts less resource expensive.

Source

actor-system.lisp.

Target Slot

timeout-timer.

Generic Function: unbecome () ¶

Reverts any behavior applied via ‘become‘ back to the default ‘receive‘ function. This function should be called from within the behavior receive function.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: unbecome () ¶

Source

actor.lisp.

Generic Function: unsubscribe (eventstream unsubscriber) ¶

Unsubscribe from the eventstream. No more events will be received then.

Package

sento.eventstream.

Source

eventstream-api.lisp.

Methods

Method: unsubscribe ((system actor-system) (unsubscriber actor)) ¶

Convenience. Allows to unsubscribe to ‘ev:eventstream‘ by just providing the ‘asys:actor-system‘.

Source

actor-system.lisp.

Method: unsubscribe ((ev-stream eventstream) (unsubscriber actor)) ¶

Unsubscribe to ‘ev:eventstream‘.

Source

eventstream.lisp.

Method: unsubscribe ((actor actor) (unsubscriber actor)) ¶

Convenience. Allows to unsubscribe to ‘ev:eventstream‘ by just providing the actor.

Source

actor.lisp.

Generic Function: unwatch (actor watcher) ¶

Unregisters ‘watcher‘ of ‘actor‘.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: unwatch ((self actor) watcher) ¶

Source

actor.lisp.

Generic Function: watch (actor watcher) ¶

Registers ‘watcher‘ as a watcher of ‘actor‘.
Watching lets the watcher know about lifecycle changes of the actor being watched.
I.e.: when it stopped. The message being sent in this case is: ‘(cons :stopped actor-instance)‘

Package

sento.actor.

Source

actor-api.lisp.

Methods

Method: watch ((self actor) watcher) ¶

Source

actor.lisp.

Generic Reader: watchers (actor) ¶

Returns a list of watchers of ‘actor‘.

Package

sento.actor.

Source

actor-api.lisp.

Methods

Reader Method: watchers ((actor actor)) ¶

List of watchers of this actor.

Target Slot

watchers.

Generic Function: workers (dispatcher) ¶

Returns the workers of this dispatcher.
But better do not touch them.
Only use the defined interface here to talk to them.

Package

sento.dispatcher.

Source

dispatcher-api.lisp.

Methods

Method: workers ((self shared-dispatcher)) ¶

Source

dispatcher.lisp.

---