Purpose

Channels are fixed-capacity local storage for typed values. They are the basic tin primitive for moving samples, commands, decoded records, or HSM events between parts of one process or firmware image.

A channel owns storage. Senders, receivers, latest readers, actors, and adapters may hold non-owning views into that storage.

API Entry Points

tin::channel<T, Capacity> for the default reject-newest policy.
tin::channel<T, Capacity, OverflowPolicy> when the overflow policy is part of the type.
tin::overflow::reject_newest, tin::overflow::drop_oldest, and tin::overflow::overwrite_latest.
sender(), receiver(), and latest_reader() for non-owning views.
try_send, try_send_from_isr, and try_receive for bounded movement.
receive() for coroutine tasks that should suspend until a value is available.

Basic FIFO Channel

#include "tin/runtime.h"
 
struct Command {
    int code{};
};
 
tin::channel<Command, 4> commands;
 
bool enqueue_command(Command command) {
    return commands.try_send(command);
}
 
bool take_command(Command& command) {
    return commands.try_receive(command);
}

The default overflow policy is reject_newest: a full channel rejects the new value and preserves already queued values.

Overflow Policies

Use drop_oldest when fresh data is more important than old data:

using Samples =

tin::channel<SensorSample, 8, tin::overflow::drop_oldest>;

Use overwrite_latest for latest-sample channels:

using Position =
  tin::channel<PositionSample, 1, tin::overflow::overwrite_latest>;
 
Position position;
auto latest = position.latest_reader();

overwrite_latest is for current-value streams. Use FIFO policies when every accepted value must be processed.

Handles

Handles narrow authority without transferring ownership.

auto tx = commands.sender();
auto rx = commands.receiver();
 
(void)tx.try_send(Command{ .code = 7 });
 
Command next{};
if (rx.try_receive(next)) {
    // Dispatch or translate the command.
}

The channel still owns the queue. The sender cannot receive, and the receiver cannot send.

Where Channels Fit

Use channels when a component needs bounded local storage. Use actors when the component also needs a step/drain execution surface. A sensor actor, for example, may own a tin::channel<Sample, 4> and expose try_receive through an output port.

Related pages: