Elixir v1.4.5 Process View Source
Conveniences for working with processes and the process dictionary.
Besides the functions available in this module, the Kernel
module
exposes and auto-imports some basic functionality related to processes
available through the functions:
Link to this section Summary
Functions
Returns true
if the process exists and is alive (i.e. it is not exiting
and has not exited yet). Otherwise, returns false
Cancels a timer created by send_after/3
Deletes the given key
from the process dictionary
If monitor_ref
is a reference which the calling process
obtained by calling monitor/1
, this monitoring is turned off.
If the monitoring is already turned off, nothing happens
Sends an exit signal with the given reason
to the pid
Sets certain flags for the process which calls this function.
Returns the old value of the flag
Returns all key-value pairs in the process dictionary
Returns the value for the given key
or default
if key
is not set
Returns all keys in the process dictionary
Returns all keys that have the given value
Returns the PID of the group leader for the process which evaluates the function
Sets the group leader of pid
to leader
. Typically, this is used when a processes
started from a certain shell should have a group leader other than :init
Puts the calling process into a wait state where its memory allocation has been reduced as much as possible, which is useful if the process does not expect to receive any messages in the near future
Returns information about the process identified by pid
, or returns nil
if the process
is not alive.
Use this only for debugging information
Returns information about the process identified by pid
,
or returns nil
if the process is not alive
Creates a link between the calling process and another process
(or port) pid
, if there is not such a link already
Returns a list of process identifiers corresponding to all the processes currently existing on the local node
The calling process starts monitoring the given item
.
It returns the monitor reference
Stores the given key
-value
pair in the process dictionary
Reads a timer created by send_after/3
Registers the given pid_or_port
under the given name
Returns a list of names which have been registered using register/2
Sends a message to the given process
Sends msg
to dest
after time
milliseconds
Sleeps the current process by timeout
Spawns the given function according to the given options
Spawns the given function from module mod
, passing the given args
according to the given options
Removes the link, if there is one, between the calling process and
the process or port referred to by pid
. Returns true
and does not
fail, even if there is no link or id
does not exist
Removes the registered name
, associated with a PID
or a port identifier
Returns the PID or port identifier with the registered name
.
Returns nil
if the name is not registered
Link to this section Types
spawn_opt :: :link | :monitor | {:priority, :low | :normal | :high} | {:fullsweep_after, non_neg_integer} | {:min_heap_size, non_neg_integer} | {:min_bin_vheap_size, non_neg_integer}
Link to this section Functions
Returns true
if the process exists and is alive (i.e. it is not exiting
and has not exited yet). Otherwise, returns false
.
pid
must refer to a process at the local node.
Inlined by the compiler.
cancel_timer(reference) :: non_neg_integer | false
Cancels a timer created by send_after/3
.
When the result is an integer, it represents the time in milliseconds left until the timer would have expired.
When the result is false
, a timer corresponding to timer_ref
could
not be found. This can be either because the timer expired, already has
been canceled, or because timer_ref
never corresponded to a timer.
If the timer has expired, the timeout message has been sent, but it does not tell you whether or not it has arrived at its destination yet.
Inlined by the compiler.
Deletes the given key
from the process dictionary.
demonitor(reference, options :: [:flush | :info]) :: boolean
If monitor_ref
is a reference which the calling process
obtained by calling monitor/1
, this monitoring is turned off.
If the monitoring is already turned off, nothing happens.
See :erlang.demonitor/2
for more info.
Inlined by the compiler.
Sends an exit signal with the given reason
to the pid
.
The following behaviour applies if reason
is any term except :normal
or :kill
:
If
pid
is not trapping exits,pid
will exit with the givenreason
.If
pid
is trapping exits, the exit signal is transformed into a message{:EXIT, from, reason}
and delivered to the message queue ofpid
.
If reason
is the atom :normal
, pid
will not exit (unless pid
is
the calling process, in which case it will exit with the reason :normal
).
If it is trapping exits, the exit signal is transformed into a message
{:EXIT, from, :normal}
and delivered to its message queue.
If reason
is the atom :kill
, that is if exit(pid, :kill)
is called,
an untrappable exit signal is sent to pid
which will unconditionally exit
with reason :killed
.
Inlined by the compiler.
Examples
Process.exit(pid, :kill)
Sets certain flags for the process which calls this function.
Returns the old value of the flag
.
See :erlang.process_flag/2
for more info.
flag(pid, :save_calls, non_neg_integer) :: non_neg_integer
Sets certain flags for the process pid
, in the same manner as flag/2
.
Returns the old value of the flag
. The allowed values for flag
are
only a subset of those allowed in flag/2
, namely :save_calls
.
See :erlang.process_flag/3
for more info.
Returns all key-value pairs in the process dictionary.
Inlined by the compiler.
Returns the value for the given key
or default
if key
is not set.
Returns all keys in the process dictionary.
Inlined by the compiler.
Returns all keys that have the given value
.
Inlined by the compiler.
Returns the PID of the group leader for the process which evaluates the function.
group_leader(pid, leader :: pid) :: true
Sets the group leader of pid
to leader
. Typically, this is used when a processes
started from a certain shell should have a group leader other than :init
.
hibernate(module, atom, list) :: no_return
Puts the calling process into a wait state where its memory allocation has been reduced as much as possible, which is useful if the process does not expect to receive any messages in the near future.
See :erlang.hibernate/3
for more info.
Inlined by the compiler.
Returns information about the process identified by pid
, or returns nil
if the process
is not alive.
Use this only for debugging information.
See :erlang.process_info/1
for more info.
info(pid, atom | [atom]) :: {atom, term} | [{atom, term}] | nil
Returns information about the process identified by pid
,
or returns nil
if the process is not alive.
See :erlang.process_info/2
for more info.
Creates a link between the calling process and another process
(or port) pid
, if there is not such a link already.
See :erlang.link/1
for more info.
Inlined by the compiler.
Returns a list of process identifiers corresponding to all the processes currently existing on the local node.
Note that a process that is exiting, exists but is not alive, i.e.,
alive?/1
will return false
for a process that is exiting,
but its process identifier will be part of the result returned.
See :erlang.processes/0
for more info.
monitor(pid | {reg_name :: atom, node :: atom} | reg_name :: atom) :: reference
The calling process starts monitoring the given item
.
It returns the monitor reference.
See the need for monitoring
for an example.
See :erlang.monitor/2
for more info.
Inlined by the compiler.
Stores the given key
-value
pair in the process dictionary.
The return value is the value that was previously stored under the key key
(or nil
in case no value was stored under key
).
read_timer(reference) :: non_neg_integer | false
Reads a timer created by send_after/3
.
When the result is an integer, it represents the time in milliseconds left until the timer will expire.
When the result is false
, a timer corresponding to timer_ref
could
not be found. This can be either because the timer expired, already has
been canceled, or because timer_ref
never corresponded to a timer.
If the timer has expired, the timeout message has been sent, but it does not tell you whether or not it has arrived at its destination yet.
Inlined by the compiler.
Registers the given pid_or_port
under the given name
.
name
must be an atom and can then be used instead of the
PID/port identifier when sending messages with Kernel.send/2
.
register/2
will fail with ArgumentError
if the PID/Port is
not existing locally and alive, if the name is already registered
or if the pid_or_port
is already registered to a different name
.
The following names are reserved and cannot be assigned to
processes nor ports: nil
, false
, true
or :undefined
.
Returns a list of names which have been registered using register/2
.
send(dest, msg, [option]) :: :ok | :noconnect | :nosuspend when dest: pid | port | atom | {atom, node}, msg: any, option: :noconnect | :nosuspend
Sends a message to the given process.
If the option :noconnect
is used and sending the message would require an
auto-connection to another node the message is not sent and :noconnect
is
returned.
If the option :nosuspend
is used and sending the message would cause the
sender to be suspended the message is not sent and :nosuspend
is returned.
Otherwise the message is sent and :ok
is returned.
Examples
iex> Process.send({:name, :node_does_not_exist}, :hi, [:noconnect])
:noconnect
send_after(pid | atom, term, non_neg_integer, [option]) :: reference when option: {:abs, boolean}
Sends msg
to dest
after time
milliseconds.
If dest
is a PID, it must be the PID of a local process, dead or alive.
If dest
is an atom, it must be the name of a registered process
which is looked up at the time of delivery. No error is given if the name does
not refer to a process.
This function returns a timer reference, which can be read or canceled with
read_timer/1
and cancel_timer/1
.
Finally, the timer will be automatically canceled if the given dest
is a PID
which is not alive or when the given PID exits. Note that timers will not be
automatically canceled when dest
is an atom (as the atom resolution is done
on delivery).
Options
:abs
- (boolean) whenfalse
,time
is treated as relative to the current monotonic time. Whentrue
,time
is the absolute value of the Erlang monotonic time at whichmsg
should be delivered todest
. To read more about Erlang monotonic time and other time-related concepts, look at the documentation for theSystem
module. Defaults tofalse
.
Sleeps the current process by timeout
.
timeout
is either the number of milliseconds to sleep as an
integer or the atom :infinity
. When :infinity
is given,
the current process will suspend forever.
Use this function with extreme care. For almost all situations
where you would use sleep/1
in Elixir, there is likely a
more correct, faster and precise way of achieving it with
message passing.
For example, if you are waiting a process to perform some action, it is better to communicate.
In other words, do not:
Task.start_link fn ->
do_something()
...
end
# Wait until work is done
Process.sleep(2000)
But do:
parent = self()
Task.start_link fn ->
do_something()
send parent, :work_is_done
...
end
receive do
:work_is_done -> :ok
after
30_000 -> :timeout # Optional timeout
end
Or even use Task.async/1
and Task.await/2
in the example
above.
Similarly, if you are waiting for a process to terminate, use monitor instead of sleep. Do not:
Task.start_link fn ->
...
end
# Wait until task terminates
Process.sleep(2000)
Instead do:
{:ok, pid} =
Task.start_link fn ->
...
end
ref = Process.monitor(pid)
receive do
{:DOWN, ^ref, _, _, _} -> :task_is_down
after
30_000 -> :timeout # Optional timeout
end
spawn((() -> any), spawn_opts) :: pid | {pid, reference}
Spawns the given function according to the given options.
The result depends on the given options. In particular,
if :monitor
is given as an option, it will return a tuple
containing the PID and the monitoring reference, otherwise
just the spawned process PID.
It also accepts extra options, for the list of available options
check :erlang.spawn_opt/4
.
Inlined by the compiler.
spawn(module, atom, list, spawn_opts) :: pid | {pid, reference}
Spawns the given function from module mod
, passing the given args
according to the given options.
The result depends on the given options. In particular,
if :monitor
is given as an option, it will return a tuple
containing the PID and the monitoring reference, otherwise
just the spawned process PID.
It also accepts extra options, for the list of available options
check :erlang.spawn_opt/4
.
Inlined by the compiler.
Removes the link, if there is one, between the calling process and
the process or port referred to by pid
. Returns true
and does not
fail, even if there is no link or id
does not exist
See :erlang.unlink/1
for more info.
Inlined by the compiler.
Removes the registered name
, associated with a PID
or a port identifier.
Fails with ArgumentError
if the name is not registered
to any PID or port.
Returns the PID or port identifier with the registered name
.
Returns nil
if the name is not registered.
See :erlang.whereis/1
for more info.