process

Types

CallError

An error returned when making a call to a process.

pub type CallError(msg) {
  CalleeDown(reason: Dynamic)
  CallTimeout
}

Constructors

```
CalleeDown(reason: Dynamic)
```
The process being called exited before it sent a response.
```
CallTimeout
```
The process being called did not response within the permitted amount of time.

Cancelled

</>

Values returned when a timer is cancelled.

pub type Cancelled {
  TimerNotFound
  Cancelled(time_remaining: Int)
}

Constructors

```
TimerNotFound
```
The timer could not be found. It probably has already triggered.
```
Cancelled(time_remaining: Int)
```
The timer was found and cancelled before it triggered.

DebugState

</>

pub external type DebugState

ExitReason

</>

pub type ExitReason {
  Normal
  Shutdown
  Abnormal(Dynamic)
}

Constructors

```
Normal
```
```
Shutdown
```
```
Abnormal(Dynamic)
```

Pid

</>

A Pid (or Process identifier) is a reference to an OTP process, which is a lightweight thread that communicates by sending and receiving messages.

pub external type Pid

PortDown

</>

A message received when a monitored port exits.

pub type PortDown {
  PortDown(port: port.Port, reason: Dynamic)
}

Constructors

PortDown(port: port.Port, reason: Dynamic)

ProcessDown

</>

A message received when a monitored process exits.

pub type ProcessDown {
  ProcessDown(pid: Pid, reason: Dynamic)
}

Constructors

```
ProcessDown(pid: Pid, reason: Dynamic)
```

Receiver

</>

A receiver is one end of a channel, it allows the owning process to receive data sent over the channel via the corresponding sender.

See the receive for receiving values, the map_receiver and merge_receiver functions for combining receivers, and new_channel for creation of a receiver.

pub external type Receiver(msg)

Reference

</>

A reference is a special value where each new one is unique. For more information references see the Erlang documentation.

pub external type Reference

Sender

</>

A sender is one end of a channel, it allows one or more processes to send data to the process that owns the channel.

See the send function for sending of values using a sender, and new_channel for creation of a sender.

pub opaque type Sender(msg)

StatusInfo

</>

pub type StatusInfo {
  StatusInfo(
    mod: Atom,
    parent: Pid,
    mode: Mode,
    debug_state: DebugState,
    state: Dynamic,
  )
}

Constructors

StatusInfo(
  mod: Atom,
  parent: Pid,
  mode: Mode,
  debug_state: DebugState,
  state: Dynamic,
)

SystemMessage

</>

pub type SystemMessage {
  GetStatus(Sender(StatusInfo))
  Suspend(Sender(Nil))
  Resume(Sender(Nil))
  GetState(Sender(Dynamic))
}

Constructors

```
GetStatus(Sender(StatusInfo))
```
```
Suspend(Sender(Nil))
```
```
Resume(Sender(Nil))
```
```
GetState(Sender(Dynamic))
```

Timer

</>

pub external type Timer

Functions

bare_message_receiver

</>

pub external fn bare_message_receiver() -> Receiver(Dynamic)

Receive a message that does not belong to any particular channel.

This function is typically not very useful when working with Gleam but it useful when working with Erlang code that sends messages to your code.

call

</>

pub fn call(sender: Sender(a), make_request: fn(Sender(b)) -> a, timeout: Int) -> b

Send a message over a channel and wait for a reply.

If the receiving process exits or does not reply within the allowed amount of time the calling process crashes. If you wish an error to be returned instead see the try_call function.

cancel_timer

</>

pub fn cancel_timer(timer: Timer) -> Cancelled

Cancel a given timer, causing it not to trigger if it has not done already.

close_channels

</>

pub external fn close_channels(Receiver(msg)) -> Nil

Close a channel, causing any future messages sent on it to be discarded.

If the sender is used to send a message after the channel is closed it is still delivered to the receiver process but it will be discarded next time the process runs any receiver.

If the receiver is for a monitor the monitor is removed and any associated messages are flushed from the message inbox.

debug_state

</>

pub external fn debug_state(List(DebugOption)) -> DebugState

flush

</>

pub external fn flush(Receiver(msg)) -> Int

Discard all messages on the channels in a given receiver.

This function must be used carefully, it may cause caller processes to crash when they do not receive a reply as their request has been dropped.

is_alive

</>

pub external fn is_alive(Pid) -> Bool

Check to see whether the process for a given Pid is alive.

See the [Erlang documentation][erl] for more information. [erl]: http://erlang.org/doc/man/erlang.html#is_process_alive-1

kill

</>

pub fn kill(pid: Pid) -> Nil

Send an untrappable kill exit signal to the target process.

See the documentation for the Erlang erlang:exit function for more information.

link

</>

pub fn link(pid: Pid) -> Nil

Creates a link between the calling process and another process.

When a process crashes any linked processes will also crash. This is useful to ensure that groups of processes that depend on each other all either succeed or fail together.

See the gleam/otp/supervisor module and the trap_exits function for mechanisms for handling process crashes.

map_receiver

</>

pub external fn map_receiver(
  Receiver(a),
  with: fn(a) -> b,
) -> Receiver(b)

Add a transformation function to a receiver. When a message is received using this receiver the tranformation function is applied to the message.

This function can be used to change the type of messages received and may be useful when combined with the merge_receiver function.

map_sender

</>

pub fn map_sender(sender: Sender(a), with mapper: fn(b) -> a) -> Sender(
  b,
)

Add a transformation function to a sender. When a message is sent using this sender the tranformation function is applied to the message before it is sent.

This function can be used to change the type of messages sent and may be useful to change the type of a sender before giving it to another process.

You may notice that this function takes a mapper function from b to a rather than from a to b as you would find in functions like list.map and receiver.map. This style of a map function may be called a “contravarient” map.

merge_receiver

</>

pub external fn merge_receiver(
  Receiver(a),
  Receiver(a),
) -> Receiver(a)

Merge one receiver into another, producing a receiver that contains the channels of both.

If a channel is found in both receivers any mapping function from the second receiver is used in the new receiver.

message_queue_size

</>

pub fn message_queue_size(pid: Pid) -> Int

Get the number of messages in the calling processes’ inbox message queue.

monitor_port

</>

pub fn monitor_port(port: Port) -> Receiver(PortDown)

Start monitoring a port. When the port exits a message is sent over the returned channel with information about the exit.

The message is only sent once, when the target port exits. If the port was not alive when this function is called the message will never be received.

Closing the channel with close_channels demonitors the port and flushes any monitor message for this channel from the message inbox.

monitor_process

</>

pub fn monitor_process(pid: Pid) -> Receiver(ProcessDown)

Start monitoring a process. When the process exits a message is sent over the returned channel with information about the exit.

The message is only sent once, when the target process exits. If the process was not alive when this function is called the message will never be received.

Closing the channel with close_channels demonitors the process and flushes any monitor message for this channel from the message inbox.

new_bare_sender

</>

pub fn new_bare_sender(pid: Pid) -> Sender(a)

Create a new channel sender that sends bare messages direct to the given process.

The messages sent using this sender are not received on any particular channel and as such are not type checked. Always favour using the new_channel function when possible as this will provide a safer and more convenient

This function may be useful when working with processes written in other BEAM languages as they may not use Gleam’s channels to receive messages.

new_channel

</>

pub fn new_channel() -> #(Sender(a), Receiver(a))

Create a new channel for processes to communicate over, returning a sender and a receiver.

The Receiver is owned by the process that calls this function and must not be sent to another process. Any process that attempts to receive on a receiver that does not belong to them will crash.

new_reference

</>

pub external fn new_reference() -> Reference

Create a new reference. The reference is unique among the currently connected nodes in the Erlang cluster.

null_sender

</>

pub fn null_sender(pid: Pid) -> Sender(a)

Create a sender that immediately discards any messages sent on it.

This may be useful for wrapping Erlang processes which do not use channels, or other situations in which you need to return a sender but do not have one available.

pid

</>

pub fn pid(sender: Sender(a)) -> Pid

Get the pid of the receiver process for a sender.

pid_from_dynamic

</>

pub external fn pid_from_dynamic(
  Dynamic,
) -> Result(Pid, List(DecodeError))

Attempt to parse a pid from some dynamic data.

This may be useful if you receive a pid in a message from an Erlang process.

receive

</>

pub external fn receive(
  receiver: Receiver(msg),
  timeout: Int,
) -> Result(msg, Nil)

Receive a message from one of the channels in a given receiver, removing it from the process inbox and returning it.

If there are no messages for this receiver in the inbox and one is not received within the timeout then an error is returned.

receive_forever

</>

pub external fn receive_forever(Receiver(msg)) -> msg

Receive a message from one of the channels in a receiver.

Be careful! This function does not return until there is a message to receive. If no message is received then the process will be stuck waiting forever.

self

</>

pub external fn self() -> Pid

Get the Pid of the process that calls the function.

send

</>

pub fn send(sender: Sender(a), message: a) -> Sender(a)

Send a message over a channel.

This function always succeeds, even if the receiving process has shut down or has closed the channel.

send_after

</>

pub fn send_after(sender: Sender(a), delay: Int, message: a) -> Timer

Send a message over a channel after a specified timeout.

send_exit

</>

pub fn send_exit(to pid: Pid, because reason: a) -> Nil

Sends an exit signal to a process, indicating that that process is to shut down.

See the [Erlang documentation][erl] for more information. [erl]: http://erlang.org/doc/man/erlang.html#exit-2

start

</>

pub external fn start(fn() -> anything) -> Pid

Start a new process from a given function.

The new process is linked to the parent process so if it crashes the parent will also crash. If you wish your program to tolerate crashes see the supervisor module.

start_unlinked

</>

pub external fn start_unlinked(fn() -> anything) -> Pid

Start a new process from a given function.

The new process is not linked to the parent process so if it crashes the issue may be silently ignored, leaving your program in an invalid state.

stop_trapping_exits

</>

pub external fn stop_trapping_exits() -> Nil

Stop trapping exits, causing any crashes in linked processes to also crash this process.

system_receiver

</>

pub external fn system_receiver() -> Receiver(SystemMessage)

Create a receiver for any system messages sent to the current process.

If you are using a higher level abstraction such as gleam/actor system messages will be handled automatically for you and this function should not be used. If you are using long lived processes without using a higher level abstraction you will need to handle system messages manually.

trap_exits

</>

pub external fn trap_exits() -> Receiver(Exit)

Start trapping exits within the current process and return a receiver.

When not trapping exits if a linked process crashes an Exit message is sent over the channel. This is the normal behaviour before this function is called.

When trapping exits (after this function is called) if a linked process crashes an Exit message is sent over the channel.

try_call

</>

pub fn try_call(sender: Sender(a), make_request: fn(Sender(b)) ->
    a, timeout: Int) -> Result(b, CallError(b))

Send a message over a channel and wait for a reply.

If the receiving process exits or does not reply within the allowed amount of time then an error is returned.

unlink

</>

pub fn unlink(pid: Pid) -> Nil

Removes any existing link between the caller process and the target process.

untyped_send

</>

pub external fn untyped_send(to: Pid, msg: msg) -> msg

Send an untyped bare message to a process.

You probably don’t want to use this function! Bare messages are not not commonly used in Gleam as they are not typed checked, see the Sender and Receiver channel types for a type safe and more ergonomic way of sending messages to processes. This function may still be useful for sending messages to processes implemented in Erlang or other BEAM languages.

Message handling is asynchronous and this function will likely return before the message is handled by the receiving processes.

See the [Erlang documentation][erl] for more information. [erl]: http://erlang.org/doc/man/erlang.html#send-2