Agents, a reference object to the result of an asynchronous computation, with additional distinctive features.

Action is a function that will be called with agent’s old state and the value it produces will be the new state of an agent. Actions are 'sent' to the agents with send! function and its variants. There are additional features which are specific to agents' actions:

  • Actions sent to the agent are enqueued and dispatched consecutively.

  • Action which throws an exception sets the agent into the failed state. The failed state may be later restarted and not yet dispatched actions will continue to process the agent’s state. See restart-agent! for details.

  • Agent’s state may be observed by tapping into the agent and validated with a custom validator function.

Actions to the agent may be dispatched even in a ref transaction. In that case, the actual sending is postponed until the transaction completes. This is done to avoid multiple sends when a transaction restarts.
Another special case is the sending of an action while currently in an action. In that case, the sends to any agent are postponed until current action completes. See release-pending-sends! for details. Note that pending sends are not dispatched if the action fails.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
(defn v
  [x]
  (nneg? x))
;;=> #'foo.bar/v

(def a (agent 0 :validator v))
;;=> #'foo.bar/a

(send! a inc)
;;=> #<[email protected]: 1>

@a
;;=> 1

(send! a dec)
;;=> #<[email protected]: 0>

(send! a dec) ;; validator fails the -1 result from dec
;;=> #<[email protected] FAILED: 0>

@a
;;=> 0

(send! a inc)
;; java.lang.RuntimeException: Agent is failed, needs restart

(restart-agent! a 5)
;;=> 5

(send! a inc)
;;=> #<[email protected]: 6>

Agent

Available since version 1.0 (view source)

TYPE

A type for agents.

See also: agent?, agent

agent

Available since version 1.0 (alias of clojure.core/agent)

Usage:
  • (agent state & options)

Type signature:
  • (Any ⨯ (Va Any)) → Agent

Creates and returns an agent with an initial value of state and zero or more options (in any order):

  • :meta metadata-map. If supplied, it will become the metadata on the agent.

  • :validator validate-fn. Must be nil or a side-effect-free fn of one argument, which will be passed the intended new state on any state change. If the new state is unacceptable, the validate-fn should return false or throw an exception.

  • :error-handler handler-fn. Ss called if an action throws an exception or if validate-fn rejects a new state.

  • :error-mode mode-keyword. May be either :continue (the default if an error-handler is given) or :fail (the default if no error-handler is given) .

Both error handler and validator may be also set and managed through their respective function in dunaj.error and dunaj.feature namespaces.

agent?

Available since version 1.0 (view source)

Usage:
  • (agent? x)

Type signature: Predicate

Returns true if object x is an instance of Agent type, false otherwise.

See also: Agent, agent

await

Available since version 1.0 (alias of clojure.core/await)

Usage:
  • (await & agents)

Type signature:
  • ((Va Agent)) → nil

Blocks the current thread (indefinitely!) until all actions dispatched thus far, from this thread or agent, to the agents have occurred. Will block on failed agents. Returns nil.

await throws if called in an action.
Will never return if a failed agent is restarted with :clear-actions set to true.

await-for

Available since version 1.0 (view source)

Usage:
  • (await-for timeout & agents)

Type signature:
  • ((U Integer+ IDuration) ⨯ (Va Agent)) → Boolean+

Blocks the current thread until all actions dispatched thus far (from this thread or agent) to the agents have occurred, or the timeout (duration) has elapsed. Returns false if returning due to timeout, true otherwise.

current-agent

Available since version 1.0 (view source)

Usage:
  • (current-agent)

Type signature:
  • () → (Maybe Agent)

Returns the agent currently running an action on this thread, else nil.

default-send-executor

Available since version 1.0 (view source)

not referred automatically

VAR of type Var

A dynamic var holding default send! executor.

default-send-off-executor

Available since version 1.0 (view source)

not referred automatically

VAR of type Var

A dynamic var holding default send-off! executor.

release-pending-sends!

Available since version 1.0 (alias of clojure.core/release-pending-sends)

Usage:
  • (release-pending-sends!)

Type signature:
  • () → Integer+

Dispatches any pending sent actions immediately. Returns the number of actions dispatched. If no action is occurring, does nothing and returns 0.

Normally, actions sent directly or indirectly during another action are held until the action completes (changes the agent’s state). This function can be used to dispatch any pending sent actions immediately.

This has no impact on actions sent during a ref transaction, which are still held until commit.

restart-agent!

Available since version 1.0 (alias of clojure.core/restart-agent)

Usage:
  • (restart-agent! agent new-state & options)

Type signature:
  • (Agent ⨯ Any ⨯ (Va Any)) → Any

When an agent is failed, changes the agent state to new-state and then un-fails the agent so that sends are allowed again.

If a :clear-actions true option is given, any actions queued on the agent that were being held while it was failed will be discarded, otherwise those held actions will proceed.

The new-state must pass the validator if any, or restart will throw an exception and the agent will remain failed with its old state and error.

Tapped channels, if any, will NOT be notified of the new state. Throws an exception if the agent is not failed. Returns new-state.

See also: await, agent

send!

Available since version 1.0 (view source)

Usage:
  • (send! a f & args)

Type signature:
  • (Agent ⨯ AnyFn ⨯ (Va Any)) → Agent

Dispatch an action to an agent. Returns the agent immediately. Subsequently, in a thread from a thread pool, the state of the agent will be set to the value of:

(apply action state-of-agent args)

Action sent during another action is held until the current action completes (changes the agent’s state).

send-off!

Available since version 1.0 (view source)

Usage:
  • (send-off! agent action & args)

Type signature:
  • (Agent ⨯ AnyFn ⨯ (Va Any)) → Agent

Dispatch a potentially blocking action to an agent. Returns the agent immediately. Subsequently, in a separate thread, the state of the agent will be set to the value of:

(apply action state-of-agent args)

Action sent during another action is held until the current action completes (changes the agent’s state).

send-via!

Available since version 1.0 (alias of clojure.core/send-via)

not referred automatically

Usage:
  • (send-via! executor agent action & args)

Type signature:
  • (IExecutor ⨯ Agent ⨯ AnyFn ⨯ (Va Any)) → Agent

Dispatch an action to an agent. Returns the agent immediately. Subsequently, in a thread supplied by executor, the state of the agent will be set to the value of:

(apply action state-of-agent args)

Action sent during another action is held until the current action completes (changes the agent’s state).

shutdown-agents!

Available since version 1.0 (view source)

Usage:
  • (shutdown-agents!)

Type signature:
  • () → nil

Initiates a shutdown of the default thread pools that back the agent system. Running actions will complete, but no new actions will be accepted. Returns nil.