otplike.process
This namespace implements core process concepts such as spawning, linking, monitoring, message passing and exiting.
Process context
All the calls made from process function directly or indirectly after it has been spawned happen in the context of the process (i.e., are issued by the process).
Process exit
A process exits when:
- it receives exit signal with reason
:kill, - it receives exit signal with the reason other than
:kill, and it doesn't trap exits, - its initial function ends (returning a value or with exception).
As there is no way to force process function to stop execution after its process has exited, a process can be alive or exiting:
- a process is alive until it exits for any reason,
- a process becomes exiting after it exited until it's initial function returns.
There can be cases when exiting process tries to communicate with
other processes. In such cases exception with the reason :noproc
is thrown.
The following happens when a process exits:
- its mailbox becomes closed so that no future messages can be received,
- all linked/monitoring processes receive exit/down signal,
- it can not be reached using its pid,
- it is no longer registered.
Signals (control messages)
Signals are used internally to manage processes. Exiting, monitoring, linking and some other operations require sending signals (not messages) to involved processes.
This namespace implements core process concepts such as spawning, linking, monitoring, message passing and exiting. ### Process context All the calls made from process function directly or indirectly after it has been spawned happen in the context of the process (i.e., are issued by the process). ### Process exit A process exits when: - it receives exit signal with reason `:kill`, - it receives exit signal with the reason other than `:kill`, and it doesn't trap exits, - its initial function ends (returning a value or with exception). As there is no way to force process function to stop execution after its process has exited, a process can be _alive_ or _exiting_: - a process is alive until it exits for any reason, - a process becomes exiting after it exited until it's initial function returns. There can be cases when exiting process tries to communicate with other processes. In such cases exception with the reason `:noproc` is thrown. The following happens when a process exits: - its mailbox becomes closed so that no future messages can be received, - all linked/monitoring processes receive exit/down signal, - it can not be reached using its pid, - it is no longer registered. ### Signals (control messages) Signals are used internally to manage processes. Exiting, monitoring, linking and some other operations require sending signals (not messages) to involved processes.
!clj
(! dest message)Sends a message to dest. dest can be a process identifier, or a
registered name.
Returns true if message was sent (dest process existed), false
otherwise.
Throws if any of arguments is nil.
Sends a `message` to `dest`. `dest` can be a process identifier, or a registered name. Returns `true` if `message` was sent (`dest` process existed), false otherwise. Throws if any of arguments is `nil`.
alive?clj
(alive?)(alive? pid)Returns true if the process exists and is alive, that is,
is not exiting and has not exited. Otherwise returns false.
When called without arguments, returns information about the calling process.
Returns `true` if the process exists and is alive, that is, is not exiting and has not exited. Otherwise returns `false`. When called without arguments, returns information about the calling process.
asynccljmacro
(async & body)Executes body asynchronously. Like go-block but propagates exceptions.
The returned value is to be passed to await!.
Executes body asynchronously. Like go-block but propagates exceptions. The returned value is to be passed to `await!`.
async-valueclj
(async-value value)Wraps value into async value.
Wraps `value` into async value.
async?clj
(async? x)Returns true if x is async value (i.e. is returned by async),
otherwise returns false.
Returns `true` if `x` is async value (i.e. is returned by `async`), otherwise returns `false`.
await!cljmacro
(await! x)Returns the value of the async operation represented by x or exits
with the same reason the operation exited. Parks until the operation is
completed if required.
It is illegal to pass the same async value to await! more than once.
Throws if x is not async value (i.e. is not returned by async).
Returns the value of the async operation represented by `x` or exits with the same reason the operation exited. Parks until the operation is completed if required. It is illegal to pass the same async value to `await!` more than once. Throws if `x` is not async value (i.e. is not returned by `async`).
await!!clj
(await!! x)The same as await! but blocks.
The same as `await!` but blocks.
await?!cljmacro
(await?! x)If x is returned by async, returns the value of the corresponding
async operation (parks if needed). If x is a regular value, returns
x.
If `x` is returned by `async`, returns the value of the corresponding async operation (parks if needed). If `x` is a regular value, returns `x`.
demonitorclj
(demonitor mref)(demonitor mref {flush? :flush})If mref is a reference that the calling process obtained by
calling monitor, this monitoring is turned off. If the monitoring
is already turned off, nothing happens. If mref is created by
other process, nothing happens.
Once demonitor has returned, it is guaranteed that no
[:DOWN monitor-ref _ _ _] message, because of the monitor,
will be placed in the caller message queue in the future.
A [:DOWN monitor-ref _ _ _] message can have been placed in
the caller message queue before the call, though. It is therefore
usually advisable to remove such a :DOWN message from the message
queue after monitoring has been stopped.
(demonitor mref {:flush true}) can be used instead of
(demonitor mref) if this cleanup is wanted.
When :flush option is true, removes (one) :DOWN message,
if there is one, from the caller message queue after monitoring
has been stopped. This is equivalent to the following:
(demonitor mref)
(selective-receive!
[_ mref _ _ _] true
(after 0
true))
Returns true.
Throws when called not in process context, or calling process is
not alive, or mref is not a ref.
If `mref` is a reference that the calling process obtained by
calling monitor, this monitoring is turned off. If the monitoring
is already turned off, nothing happens. If `mref` is created by
other process, nothing happens.
Once demonitor has returned, it is guaranteed that no
`[:DOWN monitor-ref _ _ _]` message, because of the monitor,
will be placed in the caller message queue in the future.
A `[:DOWN monitor-ref _ _ _]` message can have been placed in
the caller message queue before the call, though. It is therefore
usually advisable to remove such a `:DOWN` message from the message
queue after monitoring has been stopped.
`(demonitor mref {:flush true})` can be used instead of
`(demonitor mref)` if this cleanup is wanted.
When `:flush` option is `true`, removes (one) `:DOWN` message,
if there is one, from the caller message queue after monitoring
has been stopped. This is equivalent to the following:
```
(demonitor mref)
(selective-receive!
[_ mref _ _ _] true
(after 0
true))
```
Returns `true`.
Throws when called not in process context, or calling process is
not alive, or `mref` is not a ref.ex->reasonclj
(ex->reason e)Creates exit reason from exception.
Creates exit reason from exception.
ex-catchcljmacro
(ex-catch expr)Executes expr. Returns either result of execution or
[:EXIT reason].
Executes `expr`. Returns either result of execution or `[:EXIT reason]`.
exitclj
(exit reason)(exit pid reason)When called with one argument (reason)
Throws special exception (which can be caught). When the exception leaves process' initial function, it causes the process to exit with the specified reason.
When called with two arguments (pid and reason)
Sends an exit signal with the reason reason to the process
identified by pid.
If reason is any term, except :normal or :kill:
- if
pidis not trapping exits,piditself exits with exit reason. - if
pidis trapping exits, the exit signal is transformed into a message[:EXIT from reason]and delivered to the message queue ofpid.fromis the process identifier of the process that sent the exit signal.
If reason is :normal, pid does not exit. If pid is trapping
exits, the exit signal is transformed into a message
[:EXIT from :normal] and delivered to its message queue.
If reason is :kill, an untrappable exit signal is sent to pid,
which unconditionally exits with reason :killed.
Notice that process can exit with other reason before exit signal is processed.
Returns true if exit signal was sent (dest process existed),
false otherwise.
Throws when called not in process context, if calling process is not
alive, if pid is not a pid, or reason is nil.
**When called with one argument (reason)** Throws special exception (which can be caught). When the exception leaves process' initial function, it causes the process to exit with the specified reason. **When called with two arguments (pid and reason)** Sends an exit signal with the reason `reason` to the process identified by `pid`. If reason is any term, except `:normal` or `:kill`: - if `pid` is not trapping exits, `pid` itself exits with exit reason. - if `pid` is trapping exits, the exit signal is transformed into a message `[:EXIT from reason]` and delivered to the message queue of `pid`. `from` is the process identifier of the process that sent the exit signal. If reason is `:normal`, `pid` does not exit. If `pid` is trapping exits, the exit signal is transformed into a message `[:EXIT from :normal]` and delivered to its message queue. If reason is `:kill`, an untrappable exit signal is sent to pid, which unconditionally exits with reason `:killed`. Notice that process can exit with other reason before exit signal is processed. Returns `true` if exit signal was sent (`dest` process existed), `false` otherwise. Throws when called not in process context, if calling process is not alive, if `pid` is not a pid, or reason is `nil`.
flagclj
(flag flag value)Sets the value of a process' flag. See description of each flag below.
Flags:
:trap-exit. When set totrue, exit signals arriving to a process are converted to[:EXIT from reason]messages, which can be received as ordinary messages. If is set tofalse, the process exits if it receives an exit signal other than:normaland the exit signal is propagated to its linked processes.
Returns the old value of a flag.
Throws when called not in process context.
Sets the value of a process' flag. See description of each flag below. Flags: - `:trap-exit`. When set to `true`, exit signals arriving to a process are converted to `[:EXIT from reason]` messages, which can be received as ordinary messages. If is set to `false`, the process exits if it receives an exit signal other than `:normal` and the exit signal is propagated to its linked processes. Returns the old value of a `flag`. Throws when called not in process context.
linkclj
(link pid)Creates a link between the calling process and another process
identified by pid, if there is not such a link already. If a
process attempts to create a link to itself, nothing is done.
If pid does not exist and the calling process
- is trapping exits - the calling process receives message
[:EXIT pid :noproc]. - is not trapping exits - process exits with reason
:noproc.
Returns true.
Throws when called not in process context, or calling process is
not alive, or pid is not a pid.
Creates a link between the calling process and another process identified by `pid`, if there is not such a link already. If a process attempts to create a link to itself, nothing is done. If pid does not exist and the calling process 1. is trapping exits - the calling process receives message `[:EXIT pid :noproc]`. 2. is not trapping exits - process exits with reason `:noproc`. Returns `true`. Throws when called not in process context, or calling process is not alive, or `pid` is not a pid.
map-asyncclj
(map-async f async-val)Creates a copy of async-val adding f to the list of its
transformation functions.
Creates a copy of `async-val` adding `f` to the list of its transformation functions.
monitorclj
(monitor pid-or-name)Sends a monitor request to the entity identified by pid-or-name.
If the monitored entity does not exist or when it dies,
the caller of monitor will be notified by a message of the
following format:
[tag monitor-ref type object info]
type can be one of the following keywords: :process.
A monitor is triggered only once, after that it is removed from
both monitoring process and the monitored entity. Monitors are
fired when the monitored process terminates, or does not
exist at the moment of creation. The monitoring is also turned
off when demonitor is called.
When monitoring by name please note, that the registered-name is resolved to pid only once at the moment of monitor instantiation, later changes to the name registration will not affect the existing monitor.
When a monitor is triggered, a :DOWN message that has the
following pattern
[:DOWN monitor-ref type object info]
is sent to the monitoring process.
In monitor message monitor-ref and type are the same as described
earlier, and:
object- the monitored entity, which triggered the event. That is the argument of monitor call.info- either the exit reason of the process, or:noproc(process did not exist at the time of monitor creation).
Making several calls to monitor for the same pid-or-name is not
an error; it results in as many independent monitoring instances.
Monitoring self does nothing.
Returns monitor-ref.
Throws when called not in process context, or if calling process is not alive.
Sends a monitor request to the entity identified by `pid-or-name`. If the monitored entity does not exist or when it dies, the caller of monitor will be notified by a message of the following format: ``` [tag monitor-ref type object info] ``` `type` can be one of the following keywords: `:process`. A monitor is triggered only once, after that it is removed from both monitoring process and the monitored entity. Monitors are fired when the monitored process terminates, or does not exist at the moment of creation. The monitoring is also turned off when `demonitor` is called. When monitoring by name please note, that the registered-name is resolved to pid only once at the moment of monitor instantiation, later changes to the name registration will not affect the existing monitor. When a monitor is triggered, a `:DOWN` message that has the following pattern ``` [:DOWN monitor-ref type object info] ``` is sent to the monitoring process. In monitor message `monitor-ref` and `type` are the same as described earlier, and: - `object` - the monitored entity, which triggered the event. That is the argument of monitor call. - `info` - either the exit reason of the process, or `:noproc` (process did not exist at the time of monitor creation). Making several calls to `monitor` for the same `pid-or-name` is not an error; it results in as many independent monitoring instances. Monitoring self does nothing. Returns `monitor-ref`. Throws when called not in process context, or if calling process is not alive.
pid->strclj
(pid->str pid)Returns a string corresponding to the text representation of pid.
Throws if pid is not a process identifier.
Warning: this function is intended for debugging and is not to be used in application programs.
Returns a string corresponding to the text representation of `pid`. Throws if `pid` is not a process identifier. **Warning:** this function is intended for debugging and is not to be used in application programs.
pid?clj
(pid? pid)Returns true if pid is a process identifier, false otherwise.
Returns `true` if `pid` is a process identifier, `false` otherwise.
proc-defncljmacro
(proc-defn fname doc-string? args & body)The same as (def fname (proc-fn args body)).
The same as `(def fname (proc-fn args body))`.
proc-defn-cljmacro
(proc-defn- fname args & body)The same as proc-defn, but defines a private var.
The same as proc-defn, but defines a private var.
proc-fncljmacro
(proc-fn name-or-args & args-body)Creates process function which can be passed to spawn.
Creates process function which can be passed to `spawn`.
process-infoclj
(process-info pid)(process-info pid item-or-list)(process-info pid)
Returns a map containing information about the process identified
by pid, or nil if the process is not alive.
All items are not mandatory. The set of info-tuples being part of the result can be changed without prior notice.
The following info-tuples are part of the result: :initial-call,
:status, :message-queue-len, :links, :flags.
If the process identified by pid has a registered name, also
an info-tuple for :registered-name is included.
Warning! This function is intended for debugging only. For all other purposes, use
(process-info pid item-or-list).
Throws if pid is not a pid.
(process-info pid item-or-list)
Returns information about the process identified by pid, as
specified by into-key or info-key list. Returns nil if the
process is not alive.
If the process is alive and a single info-key is specified, the returned value is the corresponding info-tuple.
(process-info pid :messages)
=> [:messages [:msg1 [:msg2] {:msg3 3}]]
If a list of info-keys is specified, the result is a list of info-tuples. The info-tuples in the list are included in the same order as the keys were included in info-key list. Valid items can be included multiple times in item-key list.
Info-tuples:
[:initial-call [fn-symbol arity]]
fn-symbol, arity is the initial function call with which
the process was spawned.
[:links pids]
pids is a list of process identifiers, with processes to which
the process has a link.
[:message-queue-len message-queue-len]
message-queue-len is the number of messages currently in
the message queue of the process. This is the length of the list
message-queue returned as the information item messages
(see below).
[:messages message-queue]
message-queue is a list of the messages to the process,which
have not yet been processed.
[:monitored-by pids]
A list of process identifiers monitoring the process.
[:monitors monitors]
A list of monitors that are active for the process. The list consists of pids and registered names.
[:registered-name reg-name]
reg-name is the registered process name or nil if the process
has no registered name.
[:status status]
status is the status of the process and is one of the following:
:exiting:waiting(for a message):running
[:trace trace-flags]
A map of trace flags set for the process. This info-tuple is not available now but it is reserved for future.
[:flags flags]
A map of flags set for the process (e.g., {:trap-exit true}).
Throws if pid is not a pid, or specified info-key doesn't exist.
## `(process-info pid)`
Returns a map containing information about the process identified
by `pid`, or `nil` if the process is not alive.
All items are **not** mandatory. The set of info-tuples being part
of the result can be changed without prior notice.
The following info-tuples are part of the result: `:initial-call`,
`:status`, `:message-queue-len`, `:links`, `:flags`.
If the process identified by `pid` has a registered name, also
an info-tuple for `:registered-name` is included.
>**Warning!** This function is intended for debugging only.
>For all other purposes, use `(process-info pid item-or-list)`.
Throws if `pid` is not a pid.
## `(process-info pid item-or-list)`
Returns information about the process identified by `pid`, as
specified by into-key or info-key list. Returns `nil` if the
process is not alive.
If the process is alive and a single info-key is specified, the
returned value is the corresponding info-tuple.
```clojure
(process-info pid :messages)
=> [:messages [:msg1 [:msg2] {:msg3 3}]]
```
If a list of info-keys is specified, the result is a list of
info-tuples. The info-tuples in the list are included in the same
order as the keys were included in info-key list. Valid items can
be included multiple times in item-key list.
Info-tuples:
`[:initial-call [fn-symbol arity]]`
`fn-symbol`, `arity` is the initial function call with which
the process was spawned.
`[:links pids]`
`pids` is a list of process identifiers, with processes to which
the process has a link.
`[:message-queue-len message-queue-len]`
`message-queue-len` is the number of messages currently in
the message queue of the process. This is the length of the list
`message-queue` returned as the information item messages
(see below).
`[:messages message-queue]`
`message-queue` is a list of the messages to the process,which
have not yet been processed.
`[:monitored-by pids]`
A list of process identifiers monitoring the process.
`[:monitors monitors]`
A list of monitors that are active for the process.
The list consists of pids and registered names.
`[:registered-name reg-name]`
`reg-name` is the registered process name or `nil` if the process
has no registered name.
`[:status status]`
`status` is the status of the process and is one of the following:
- `:exiting`
- `:waiting` (for a message)
- `:running`
`[:trace trace-flags]`
A map of trace flags set for the process.
_This info-tuple is not available now but it is reserved for
future._
`[:flags flags]`
A map of flags set for the process (e.g., `{:trap-exit true}`).
Throws if `pid` is not a pid, or specified info-key doesn't exist.processesclj
(processes)Returns a sequence of process identifiers corresponding to all the processes currently existing.
Notice that an exiting process exists, but is not alive.
That is, (alive? pid) returns false for an exiting process,
but its process identifier is part of the result returned from
(processes).
Returns a sequence of process identifiers corresponding to all the processes currently existing. Notice that an exiting process exists, but is not alive. That is, `(alive? pid)` returns `false` for an exiting process, but its process identifier is part of the result returned from `(processes)`.
receive!cljmacro
(receive! & clauses)Receives and removes from the inbox the first message sent to the
process using the ! function:
(receive!
pattern1 pattern-expr1
pattern2 pattern-expr2
...)
The message is matched using clojure.core.match/match against the
patterns. If a match succeeds, the corresponding expression is
evaluated, otherwise throws. It is illegal to use a receive! with
no patterns.
If there are no messages in the inbox, the execution is suspended, possibly indefinitely, until the first message arrives.
The receive expression can be augmented with a timeout:
(receive!
pattern pattern-expr
...
(after timeout
timeout-expr))
There are two special cases for the timeout value:
:infinity - the process is to wait indefinitely for a matching
message. This is the same as not using a timeout. This can be
useful for timeout values that are calculated at runtime.
0 - if there is no messages in the mailbox, or the first message
doesn't match, the timeout occurs immediately.
Returns the value of the evaluated expression.
Receives and removes from the inbox the first message sent to the
process using the `!` function:
```
(receive!
pattern1 pattern-expr1
pattern2 pattern-expr2
...)
```
The message is matched using `clojure.core.match/match` against the
patterns. If a match succeeds, the corresponding expression is
evaluated, otherwise throws. It is illegal to use a `receive!` with
no patterns.
If there are no messages in the inbox, the execution is suspended,
possibly indefinitely, until the first message arrives.
The receive expression can be augmented with a timeout:
```
(receive!
pattern pattern-expr
...
(after timeout
timeout-expr))
```
There are two special cases for the `timeout` value:
`:infinity` - the process is to wait indefinitely for a matching
message. This is the same as not using a timeout. This can be
useful for timeout values that are calculated at runtime.
`0` - if there is no messages in the mailbox, or the first message
doesn't match, the timeout occurs immediately.
Returns the value of the evaluated expression.receive!!cljmacro
(receive!! & clauses)The same as receive! but blocks.
The same as `receive!` but blocks.
ref?clj
(ref? x)Returns true if x is a reference, false otherwise.
Returns `true` if `x` is a reference, `false` otherwise.
registeredclj
(registered)Returns a set of names of the processes that have been registered.
Returns a set of names of the processes that have been registered.
resolve-pidclj
(resolve-pid pid-or-name)If pid-or-name is a pid - returns pid. If a registered name -
returns the pid of registered process. Else returns nil.
If `pid-or-name` is a pid - returns pid. If a registered name - returns the pid of registered process. Else returns `nil`.
selective-receive!cljmacro
(selective-receive! & clauses)The same as receive! but doesn't crash if the first message
doesn't match. Instead waits for the matching message, removes it
from the mailbox leaving all the rest messages in the original order.
When the timeout is 0, checks all the messages in the mailbox
and not the first one only.
The same as `receive!` but doesn't crash if the first message doesn't match. Instead waits for the matching message, removes it from the mailbox leaving all the rest messages in the original order. When the timeout is `0`, checks all the messages in the mailbox and not the first one only.
selfclj
(self)Returns the process identifier of the calling process. Throws when called not in process context, or process is not alive.
Returns the process identifier of the calling process. Throws when called not in process context, or process is not alive.
spawnclj
(spawn proc-func)(spawn proc-func args)Returns the process identifier of a new process started by the
application of proc-fun to args.
Returns the process identifier of a new process started by the application of `proc-fun` to `args`.
spawn-linkclj
(spawn-link proc-func)(spawn-link proc-func args)Returns the process identifier of a new process started by the
application of proc-fun to args. A link is created between the
calling process and the new process, atomically. Otherwise works
like spawn.
Throws when called not in process context, or calling process is not alive.
Returns the process identifier of a new process started by the application of `proc-fun` to `args`. A link is created between the calling process and the new process, atomically. Otherwise works like `spawn`. Throws when called not in process context, or calling process is not alive.
spawn-optclj
(spawn-opt proc-func opts)(spawn-opt proc-func args opts)Returns the process identifier of a new process started by the
application of proc-fun to args.
options argument is a map of option names (keywords) to their
values.
The following options are allowed:
:flags- a map of process' flags (e.g.{:trap-exit true}):link- iftrue, sets a link to the parent process:register- name to register the process, can not be pid, if name isnilprocess will not be registered
Throws
- when there is another process registered under the same name,
- on invalid arguments.
Returns the process identifier of a new process started by the
application of `proc-fun` to `args`.
`options` argument is a map of option names (keywords) to their
values.
The following options are allowed:
- `:flags` - a map of process' flags (e.g. `{:trap-exit true}`)
- `:link` - if `true`, sets a link to the parent process
- `:register` - name to register the process, can not be pid, if name is
`nil` process will not be registered
Throws
- when there is another process registered under the same name,
- on invalid arguments.unlinkclj
(unlink pid)Removes the link, if there is one, between the calling process and
the process referred to by pid.
Returns true.
Does not fail if there is no link to pid, if pid is self pid, or
if pid does not exist.
Once unlink has returned, it is guaranteed that the link between
the caller and the entity referred to by pid has no effect on the
caller in the future (unless the link is setup again).
If the caller is trapping exits, an [:EXIT pid _] message from
the link can have been placed in the caller's message queue before
the call.
Notice that the [:EXIT pid _] message can be the result of the
link, but can also be the result of pid calling exit. Therefore,
it can be appropriate to clean up the message queue when trapping
exits after the call to unlink.
Throws when called not in process context, or calling process
is not alive, or pid is not a pid.
Removes the link, if there is one, between the calling process and the process referred to by `pid`. Returns `true`. Does not fail if there is no link to `pid`, if `pid` is self pid, or if `pid` does not exist. Once `unlink` has returned, it is guaranteed that the link between the caller and the entity referred to by `pid` has no effect on the caller in the future (unless the link is setup again). If the caller is trapping exits, an `[:EXIT pid _]` message from the link can have been placed in the caller's message queue before the call. Notice that the `[:EXIT pid _]` message can be the result of the link, but can also be the result of pid calling exit. Therefore, it can be appropriate to clean up the message queue when trapping exits after the call to unlink. Throws when called not in process context, or calling process is not alive, or `pid` is not a pid.
whereisclj
(whereis reg-name)Returns the process identifier with the registered name reg-name,
or nil if the name is not registered.
Returns the process identifier with the registered name `reg-name`, or `nil` if the name is not registered.
with-asynccljmacro
(with-async [binding-form async-expr :as bindings] & body)Wraps body into a function with binding-form as its single
argument.
Returns (map-async body-fn async-expr-result).
Works as a recursion point for body.
Wraps `body` into a function with binding-form as its single argument. Returns `(map-async body-fn async-expr-result)`. Works as a recursion point for `body`.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close