Elixir v1.1.0 Process

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:

Summary

Functions

alive?(pid)

Returns true if the process exists and is alive (i.e. it is not exiting and has not exited yet). Otherwise, returns false

delete(key)

Deletes the given key from the dictionary

demonitor(monitor_ref, options \\ [])

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

exit(pid, reason)

Sends an exit signal with the given reason to the pid

flag(flag, value)

Sets certain flags for the process which calls this function. Returns the old value of the flag

flag(pid, flag, value)

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

get()

Returns all key-values in the dictionary

get(key, default \\ nil)

Returns the value for the given key

get_keys(value)

Returns all keys that have the given value

group_leader()

Returns the pid of the group leader for the process which evaluates the function

group_leader(pid, leader)

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(mod, fun, args)

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

info(pid)

Returns information about the process identified by pid or nil if the process is not alive. Use this only for debugging information

info(pid, spec)

Returns information about the process identified by pid or nil if the process is not alive

link(pid)

Creates a link between the calling process and another process (or port) pid, if there is not such a link already

list()

Returns a list of process identifiers corresponding to all the processes currently existing on the local node

monitor(item)

The calling process starts monitoring the item given. It returns the monitor reference

put(key, value)

Stores the given key-value in the process dictionary

Associates the name with a pid or a port identifier. name, which must be an atom, can be used instead of the pid / port identifier with the Kernel.send/2 function

registered()

Returns a list of names which have been registered using register/2

send(dest, msg, options)

Sends a message to the given process

send_after(dest, msg, time)

Sends msg to dest after time milliseconds

spawn(fun, opts)

Spawns the given module and function passing the given args according to the given options

spawn(mod, fun, args, opts)

Spawns the given module and function passing the given args according to the given options

unlink(pid)

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

unregister(name)

Removes the registered name, associated with a pid or a port identifier

whereis(name)

Returns the pid or port identifier with the registered name. Returns nil if the name is not registered

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}

spawn_opts :: [spawn_opt]

Functions

alive?(pid)

Specs

alive?(pid) :: boolean

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.

delete(key)

Specs

delete(term) :: term | nil

Deletes the given key from the dictionary.

demonitor(monitor_ref, options \\ [])

Specs

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.

exit(pid, reason)

Specs

exit(pid, term) :: true

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 given 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.
If reason is the atom :normal, pid will not exit (unless it is the calling process’s pid, 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 exit reason :killed.

Inlined by the compiler.

Examples

Process.exit(pid, :kill)

flag(flag, value)

Specs

flag(process_flag, term) :: term

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, flag, value)

Specs

flag(pid, :save_calls, non_neg_integer) :: non_neg_integer

See :erlang.process_flag/3 for more info.

get()

Specs

get :: [{term, term}]

Returns all key-values in the dictionary.

get(key, default \\ nil)

Specs

get(term, default :: term) :: term

Returns the value for the given key.

get_keys(value)

Specs

get_keys(term) :: [term]

Returns all keys that have the given value.

group_leader()

Specs

group_leader :: pid

Returns the pid of the group leader for the process which evaluates the function.

group_leader(pid, leader)

Specs

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(mod, fun, args)

Specs

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.

info(pid)

Specs

info(pid) :: Keyword.t

Returns information about the process identified by pid or nil if the process is not alive. Use this only for debugging information.

See :erlang.process_info/1 for more info.

info(pid, spec)

Specs

info(pid, atom | [atom]) ::
  {atom, term} |
  [{atom, term}] |
  nil

Returns information about the process identified by pid or nil if the process is not alive.

See :erlang.process_info/2 for more info.

link(pid)

Specs

link(pid | port) :: true

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.

list()

Specs

list :: [pid]

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(item)

Specs

monitor(pid | {reg_name :: atom, node :: atom} | reg_name :: atom) :: reference

The calling process starts monitoring the item given. It returns the monitor reference.

See :erlang.monitor/2 for more info.

Inlined by the compiler.

put(key, value)

Specs

put(term, term) :: term | nil

Stores the given key-value in the process dictionary.

Specs

register(pid | port, atom) :: true

Associates the name with a pid or a port identifier. name, which must be an atom, can be used instead of the pid / port identifier with the Kernel.send/2 function.

Process.register/2 will fail with ArgumentError if the pid supplied is no longer alive, (check with alive?/1) or if the name is already registered (check with whereis/1).

registered()

Specs

registered :: [atom]

Returns a list of names which have been registered using register/2.

send(dest, msg, options)

Specs

send(dest, msg, [option]) :: result when dest: pid | port | atom | {atom, node}, msg: any, option: :noconnect | :nosuspend, result: :ok | :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(dest, msg, time)

Specs

send_after(pid | atom, term, non_neg_integer) :: reference

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 :erlang.read_timer/1, :erlang.start_timer/3 and :erlang.cancel_timer/1. Note time cannot be greater than 4294967295.

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

spawn(fun, opts)

Specs

spawn((() -> any), spawn_opts) ::
  pid |
  {pid, reference}

Spawns the given module and function 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.

spawn(mod, fun, args, opts)

Specs

spawn(module, atom, list, spawn_opts) ::
  pid |
  {pid, reference}

Spawns the given module and function passing the given args according to the given options.

It also accepts extra options, for the list of available options check :erlang.spawn_opt/4.

Inlined by the compiler.

unlink(pid)

Specs

unlink(pid | port) :: true

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.

unregister(name)

Specs

unregister(atom) :: true

Removes the registered name, associated with a pid or a port identifier.

See :erlang.unregister/1 for more info.

whereis(name)

Specs

whereis(atom) :: pid | port | nil

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.