gleam_otp

gleam/otp/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.

DebugOption 

pub type DebugOption {
  NoDebug
}

Constructors

  • NoDebug

DebugState 

pub external type DebugState

Exit

A message received when a linked process exits when the current process is trapping exits.

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

Constructors

  • Exit(pid: Pid, reason: Dynamic)

ExitReason 

pub type ExitReason {
  Normal
  Shutdown
  Abnormal(Dynamic)
}

Constructors

  • Normal
  • Shutdown
  • Abnormal(Dynamic)

Mode 

pub type Mode {
  Running
  Suspended
}

Constructors

  • Running
  • Suspended

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, reason: Dynamic)
}

Constructors

  • PortDown(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.

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

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.

See also the trap_exits function.

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.

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 a bare message to a process. These bare messages are not not commonly used in Gleam as they are not typed checked, see the Channel type 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