%--------------------------------------------------%
% vim: ft=mercury ts=4 sw=4 et
%--------------------------------------------------%
% Copyright (C) 2000-2001, 2006-2007 The University of Melbourne.
% Copyright (C) 2014-2015, 2018, 2020-2022, 2025-2026 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: thread.channel.m.
% Main author: petdr.
% Stability: medium.
%
% An mvar can contain only a single value. On the other hand,
% a channel provides unbounded buffering.
%
% For example, a program could consist of two worker threads and one logging
% thread. The worker threads can place messages into the channel, and they
% will be buffered for processing by the logging thread.
%
%--------------------------------------------------%
%--------------------------------------------------%

:- module thread.channel.
:- interface.

:- import_module io.
:- import_module maybe.

%--------------------------------------------------%

:- type channel(T).

    % Initialise a channel.
    %
:- pred init(channel(T)::out, io::di, io::uo) is det.

    % Put an item at the end of the channel.
    %
:- pred put(channel(T)::in, T::in, io::di, io::uo) is det.

    % Take an item from the start of the channel.
    % If there is nothing in the channel, block.
    %
:- pred take(channel(T)::in, T::out, io::di, io::uo) is det.

    % Take an item from the start of the channel.
    % If there is nothing in the channel, return "no" immediately.
    %
:- pred try_take(channel(T)::in, maybe(T)::out, io::di, io::uo) is det.

    % Duplicate a channel. The new channel sees all (and only) the
    % data written to the channel after the `duplicate'/4 call.
    %
:- pred duplicate(channel(T)::in, channel(T)::out, io::di, io::uo)
    is det.

    % Place an item back at the start of the channel.
    %
    % WARNING: a call to channel.untake will deadlock if a call to
    % channel.take is blocked on the same channel.
    %
:- pred untake(channel(T)::in, T::in, io::di, io::uo) is det.
:- pragma obsolete(pred(untake/4)).

%--------------------------------------------------%
%--------------------------------------------------%