Channel

Owns a bounded FIFO with suspension-backed send/receive backpressure. Creation pre-reserves all slots. Successful send transfers one owned payload; failed send returns it in ChannelSendError. Immediate receives distinguish temporary Empty from final Closed; asynchronous receives return optional EOF. Close stops new send commits and drains committed items before EOF. Cancellation can remove pending permit waits, never duplicate a committed payload. Published readonly borrows may operate concurrently; moving/disposal requires ordinary synchronization and live-loan rules. No fairness or waiter-order guarantee. Queue operations/Close briefly contend on an internal mutex; guards never cross await. Creation allocates; ordinary successful transfers do not grow backing. Destruction closes before releasing state; pending work retains private leases. Element move/destruction costs and traps remain those of T.

Module std.sync

import std.sync;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

pub final class Channel<T> where T: Movable

Example

module example.channel;
from std.sync import Channel;
from std.task import Task;
async fn Main() -> Task<i32> {
    var Queue = {
        // The scoped Result keeps its exact writable payload until transfer.
        var QueueCreation = Channel<i32>.TryCreate(1);
        switch QueueCreation {
            case .Ok { Value = Value: mut Channel<i32>& } => break move(Value);
            case .Err => return 1;
        }
    };
    if Queue.Capacity != 1 { return 2; }
    if Queue.TrySend(40) is .Err { Error = _ } { return 3; }
    switch Queue.TrySend(2) {
        case .Ok => return 4;
        case .Err { Error = Error } => {
            if !(Error.Reason is .Full) || Error.Value != 2 { return 5; }
        }
    }
    switch Queue.TryReceive() {
        case .Ok { Value = PatternPayload2 } => {
            switch PatternPayload2 {
                case .Item { Value = Value } => { if Value != 40 { return 6; } }
                default => return 7;
            }
        }
        default => return 7;
    }
    switch Queue.TryReceive() {
        case .Ok { Value = PatternPayload3 } if (PatternPayload3 is .Empty) => {}
        default => return 8;
    }
    if await Queue.SendAsync(42) is .Err { Error = _ } { return 9; }
    if Queue.Close() is .Err { Error = _ } { return 10; }
    switch await Queue.ReceiveAsync() {
        case .Ok { Value = PatternPayload4 } => {
            switch PatternPayload4 {
                case .Some { Value = Value } => { if Value != 42 { return 11; } }
                default => return 12;
            }
        }
        default => return 12;
    }
    switch await Queue.ReceiveAsync() {
        case .Ok { Value = PatternPayload5 } if (PatternPayload5 is .None) => {}
        default => return 13;
    }
    switch Queue.TrySend(99) {
        case .Err { Error = Error } => { if !(Error.Reason is .Closed) || Error.Value != 99 { return 14; } }
        case .Ok => return 15;
    }
    var Moved = move(Queue);
    if !Queue.IsEmpty || Moved.IsEmpty { return 16; }
    if Moved.Close() is .Err { Error = _ } { return 17; }
    return 0;
}

Channel.init

pub init()

Creates inert owner without allocating.

Channel.init

pub init(Source: readonly Self&) = delete;

Rejects duplicate visible closing authority. Source: Existing owner.

Channel.init

pub init(Source: mut Self&&)

Transfers closing authority, preserving separately retained operations. Source: Owner left inert.

Channel.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects duplicate closing authority. Source: Existing owner. Return: No runtime result; this assignment is deleted and cannot be invoked.

Channel.operator

pub fn operator =(Source: mut Self&&) -> void = delete;

Rejects implicit close-and-replace because close can report failure. Source: Existing owner. Return: No runtime result; this assignment is deleted and cannot be invoked.

Channel.IsEmpty

pub IsEmpty: bool;

Observes default/moved owner identity; not queue occupancy.

Channel.Capacity

pub Capacity: usize;

Observes logical bound, or zero for inert owner.

Channel.TryCreate

pub static fn TryCreate(Capacity: usize) -> Result<Self, ChannelError>

Allocates bounded FIFO and native/shared synchronization transactionally. Capacity: Positive logical capacity representable as u64; zero/overflow return InvalidCapacity. Return: Published owner or portable error; partial resources clean up normally. Warning: May allocate and acquire provider resources.

Channel.TrySend

pub readonly fn TrySend(mut Value: T) -> Result<void, ChannelSendError<T>>

Attempts one send without waiting for capacity. Value: Owned item transferred on success, returned on failure. Return: Ok or exact owning error, including Full/Closed/EmptyOwner. Warning: May briefly contend on queue mutex.

Channel.SendAsync

pub readonly async fn SendAsync(mut Value: T, mut Token: CancellationToken) -> Task<Result<void, ChannelSendError<T>>>

Waits asynchronously for capacity, then attempts an owned FIFO commit. Value: Owned input held until commit or returned failure. Token: Owned cancellation observation; cancellation only removes pending wait. Return: Task yielding Ok or error retaining the exact unsent value. Warning: Receiver/storage loans last through completion; no mutex guard crosses await.

Channel.SendAsync

pub readonly fn SendAsync(mut Value: T) -> Task<Result<void, ChannelSendError<T>>>

Supplies the omitted arguments to SendAsync. Note: Defaults: Token = CancellationToken(). Value: Same input, ownership and lifetime contract as the full operation. Return: Exact full-operation result; no additional async frame is created.

Channel.TryReceive

pub readonly fn TryReceive() -> Result<ChannelReceive<T>, ChannelError>

Attempts receive without waiting for item arrival. Return: Owned Item, open Empty, final Closed, or portable failure. Warning: May briefly contend on queue mutex.

Channel.ReceiveAsync

pub readonly async fn ReceiveAsync(mut Token: CancellationToken) -> Task<Result<T?, ChannelError>>

Waits asynchronously for one item, draining buffered values after close. Token: Owned cancellation observation, effective only while pending. Return: Task yielding owned optional item, none for closed EOF, or portable error. Warning: Receiver/storage loans last through completion; no guard crosses await.

Channel.ReceiveAsync

pub readonly fn ReceiveAsync() -> Task<Result<T?, ChannelError>>

Supplies the omitted arguments to ReceiveAsync. Note: Defaults: Token = CancellationToken(). Return: Exact full-operation result; no additional async frame is created.

Channel.CreateAsyncIterator

pub readonly fn CreateAsyncIterator() -> ChannelAsyncIterator<T>

Creates retained consumer state without receiving or allocating backing. Return: Noncopy cursor competing for this FIFO; inert owner yields inert cursor. Warning: Cursor retention does not prevent visible-owner cleanup from closing the channel; committed items remain drainable afterward.

Channel.Close

pub readonly fn Close() -> Result<void, ChannelError>

Idempotently forbids sends and wakes waits; committed values remain drainable. Return: Ok for inert/already closed owner, or unchanged-state lock error. Warning: May briefly contend on queue mutex.