This module works only with one of --mm:arc / --mm:atomicArc / --mm:orc compilation flags.

This module implements multi-producer multi-consumer channels - a concurrency primitive with a high-level interface intended for communication and synchronization between threads. It allows sending and receiving typed, isolated data, enabling safe and efficient concurrency.

The Chan type represents a generic fixed-size channel object that internally manages the underlying resources and synchronization. It has to be initialized using the newChan proc. Sending and receiving operations are provided by the blocking send and recv procs, and non-blocking trySend and tryRecv procs. Send operations add messages to the channel, receiving operations remove them.

See also:

• std/isolation

The following is a simple example of two different ways to use channels: blocking and non-blocking.

Example: cmd: --threads:on --gc:orc

import threading/channels
import std/os

# In this example a channel is declared at module scope.
# Channels are generic, and they include support for passing objects between
# threads.
# Note that isolated data passed through channels is moved around.
var chan = newChan[string]()

block example_blocking:
  # This proc will be run in another thread.
  proc basicWorker() =
    chan.send("Hello World!")

  # Launch the worker.
  var worker: Thread[void]
  createThread(worker, basicWorker)

  # Block until the message arrives, then print it out.
  var dest = ""
  dest = chan.recv()
  assert dest == "Hello World!"

  # Wait for the thread to exit before moving on to the next example.
  worker.joinThread()

block example_non_blocking:
  # This is another proc to run in a background thread. This proc takes a while
  # to send the message since it first sleeps for some time.
  proc slowWorker(delay: Natural) =
    # `delay` is a period in milliseconds
    sleep(delay)
    chan.send("Another message")

  # Launch the worker with a delay set to 2 seconds (2000 ms).
  var worker: Thread[Natural]
  createThread(worker, slowWorker, 2000)

  # This time, use a non-blocking approach with tryRecv.
  # Since the main thread is not blocked, it could be used to perform other
  # useful work while it waits for data to arrive on the channel.
  var messages: seq[string]
  while true:
    var msg = ""
    if chan.tryRecv(msg):
      messages.add msg # "Another message"
      break
    messages.add "Pretend I'm doing useful work..."
    # For this example, sleep in order not to flood the sequence with too many
    # "pretend" messages.
    sleep(400)

  # Wait for the second thread to exit before cleaning up the channel.
  worker.joinThread()

  # Thread exits right after receiving the message
  assert messages[^1] == "Another message"
  # At least one non-successful attempt to receive the message had to occur.
  assert messages.len >= 2