Package {mizu}

Title:	Single-Producer Single-Consumer Channels
Version:	0.0.1
Description:	Provides a single-producer single-consumer channel with bounded capacity, optional timeouts on receives, and sentinel return values for full, timeout, and closed states. The ring buffer is implemented in C: sends and receives are constant-time operations, values are delivered in first-in first-out order, and a closed channel drains its buffered values before reporting the closed state. The transport is in-process: both ends of a channel live in the calling R process, which suits the channel to prototyping producer and consumer designs and to testing channel-based logic.
License:	MIT + file LICENSE
URL:	https://github.com/shikokuchuo/mizu-r
BugReports:	https://github.com/shikokuchuo/mizu-r/issues
Depends:	R (≥ 4.1)
Suggests:	testthat (≥ 3.0.0)
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.1.0
Config/testthat/edition:	3
Encoding:	UTF-8
NeedsCompilation:	yes
Packaged:	2026-09-21 10:22:47 UTC; shikokuchuo
Author:	Charlie Gao [aut, cre], Posit Software, PBC [cph, fnd]
Maintainer:	Charlie Gao <charlie.gao@posit.co>
Repository:	CRAN
Date/Publication:	2026-09-30 09:40:07 UTC

Sentinel Values

Description

Singletons returned by mizu_send() and mizu_recv() that tag the terminal states of a channel as ordinary values, not signalled conditions, so hot loops stay branch-cheap. Dispatch with inherits(x, "mizu_sentinel") or on the specific class; use mizu_is_sentinel() where payloads are untrusted.

Usage

mizu_full

mizu_timeout

mizu_closed

Details

• mizu_full — the buffer is at capacity (mizu_send()).

• mizu_timeout — no value arrived within timeout (mizu_recv()).

• mizu_closed — the channel is closed and drained (mizu_inproc_close()).

Create a Channel

Description

Creates a single-producer single-consumer channel: a bounded ring buffer that holds up to capacity values until they are received. The ring buffer is implemented in C, with O(1) sends and receives. The transport is in-process — both ends of the channel live in the calling R process.

Usage

mizu_inproc_channel(capacity)

Arguments

Details

This interface is experimental and may change in a future release.

Value

A channel (class "mizu_inproc_channel").

Examples

ch <- mizu_inproc_channel(2)
mizu_send(ch, "a")
mizu_send(ch, 42)
mizu_recv(ch)
mizu_recv(ch)
mizu_inproc_close(ch)

Close a Channel

Description

Orderly shutdown. Values buffered before the close remain receivable; further sends return the mizu_closed sentinel, and a receive on a drained channel returns the same. Closing an already-closed channel is a no-op.

Usage

mizu_inproc_close(ch)

Arguments

Value

Invisibly, TRUE.

Examples

ch <- mizu_inproc_channel(1)
mizu_send(ch, "a")
mizu_inproc_close(ch)
mizu_recv(ch)
mizu_recv(ch)

Test for a mizu Sentinel

Description

Identity comparison against the interned sentinel singletons — mizu_full, mizu_timeout, and mizu_closed — that the verbs of mizu return to tag terminal states. inherits(x, "mizu_sentinel") tests the class alone, which any payload can carry. This includes a genuine sentinel forwarded over a channel, which arrives as an ordinary copy. mizu_is_sentinel() is provenance: TRUE only for the exact objects that the own calls of mizu return. So code that relays untrusted values can distinguish its terminal states from look-alike payloads.

Usage

mizu_is_sentinel(x)

Arguments

Details

Sentinels are ordinary values, not R conditions: nothing is signalled, and condition handlers never see them.

Value

TRUE or FALSE.

Examples

ch <- mizu_inproc_channel(1)
x <- mizu_recv(ch, timeout = 0)
mizu_is_sentinel(x)
mizu_is_sentinel(42)
# class alone does not make a sentinel:
mizu_is_sentinel(
  structure("x", class = c("mizu_timeout", "mizu_sentinel"))
)
mizu_inproc_close(ch)

Send and Receive over a Channel

Description

mizu_send() appends x to the buffer of the channel. Sends never block: a send on a full channel returns the mizu_full sentinel immediately. mizu_recv() removes and returns the oldest buffered value, waiting up to timeout seconds for one to arrive.

Usage

mizu_send(ch, x)

mizu_recv(ch, timeout = Inf)

Arguments

Details

Terminal states surface as class-tagged sentinels, not errors. Dispatch with inherits(x, "mizu_sentinel"), or on the specific classes:

• mizu_full — the buffer is at capacity (send). Receive first, or drop the value.

• mizu_timeout — no value arrived within timeout (recv).

• mizu_closed — the channel was closed with mizu_inproc_close(). A receive drains all buffered values before it reports this.

NULL is a legal payload. Sentinels are ordinary values, identifiable by class alone, and never signalled conditions. mizu_is_sentinel() checks identity where payloads are untrusted.

Value

mizu_send() returns TRUE (invisibly) on success, or a sentinel otherwise. mizu_recv() returns the received value or a sentinel.

Examples

ch <- mizu_inproc_channel(1)
mizu_send(ch, "a")
mizu_send(ch, "b")  # full: returns the mizu_full sentinel
mizu_recv(ch)
mizu_recv(ch, timeout = 0)
mizu_inproc_close(ch)

Print Methods for mizu Objects

Description

One-line summaries. A channel prints its state — open or closed — and the number of buffered values out of its capacity. Sentinels print as their class. The methods never error, so auto-printing is always safe.

Usage

## S3 method for class 'mizu_inproc_channel'
print(x, ...)

## S3 method for class 'mizu_sentinel'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

ch <- mizu_inproc_channel(2)
ch
mizu_send(ch, "a")
ch
mizu_inproc_close(ch)