continue_stream

A Swift-style AsyncIterator.Continuation-style channel for Rust.

This crate provides a lightweight, single-producer single-consumer (SPSC) channel designed specifically for bridging synchronous and asynchronous code. It's the streaming counterpart to the continue crate, optimized for sending multiple values over time rather than a single result.

Key Features

Sync-to-async bridge: Synchronous senders, asynchronous receivers
Buffered: Multiple items can be sent before the receiver polls
Cancellation-aware: Both sides can detect when the other has been dropped
Stream implementation: Receivers implement futures::Stream for ergonomic async iteration
Lightweight: No cloning overhead, optimized for single-producer single-consumer use
no_std compatible: Works in embedded and WASM environments with alloc

Design Philosophy

Like the continue crate:

The send-side is synchronous, and the receive-side is asynchronous, as this crate is designed as a primitive used to bridge synchronous and asynchronous code.
Cancellation is thoughtfully supported and considered in the design.
The channel is a single-producer, single-consumer pair. Bring your own Clone, or consider more complex solutions if you need multiple producers or consumers.

Unlike the continue crate:

The channel is buffered, allowing the sender to send multiple items before the receiver polls.
Dropping an unsent sender does not panic but instead gracefully terminates the stream by producing None on the receiver.

Unlike more complex channel types:

Avoiding Clone simplifies the problem and unlocks the potential for more efficient implementations.
Focus on bridging sync and async code makes threading behavior more defined and predictable.

Usage

Add this to your Cargo.toml:

[dependencies]
continue_stream = "0.1.0"

For no_std environments (embedded, WASM):

[dependencies]
continue_stream = { version = "0.1.0", default-features = false }

Platform Support

no_std compatible: Works without the standard library, only requires alloc
Full functionality: All features including threading work in both std and no_std environments

Examples

Basic Usage

use continue_stream::continuation;

let (sender, receiver) = continuation::<i32>();

// Send from synchronous code
sender.send(1);
sender.send(2);
sender.send(3);
drop(sender); // Signal completion

// Receive in async code
while let Some(value) = receiver.receive().await {
    println!("Received: {}", value);
}

Using as a Stream

use continue_stream::continuation;
use futures::StreamExt;

let (sender, receiver) = continuation::<String>();

// Send some messages
sender.send("Hello".to_string());
sender.send("World".to_string());
drop(sender);

// Use Stream combinators
let messages: Vec<String> = receiver.collect().await;
assert_eq!(messages, vec!["Hello", "World"]);

Cross-thread Communication

use continue_stream::continuation;
use std::thread;
use std::time::Duration;

let (sender, receiver) = continuation::<i32>();

// Spawn a thread that sends values
thread::spawn(move || {
    for i in 0..5 {
        sender.send(i);
        thread::sleep(Duration::from_millis(10));
    }
    // Sender is dropped here, signaling completion
});

// Receive values asynchronously
let mut count = 0;
while let Some(value) = receiver.receive().await {
    assert_eq!(value, count);
    count += 1;
}
assert_eq!(count, 5);

Cancellation Detection

use continue_stream::continuation;

let (sender, receiver) = continuation::<i32>();

// Drop the receiver to cancel
drop(receiver);

// Sender can detect cancellation
assert!(sender.is_cancelled());

API

The crate provides three main types:

`continuation<T>() -> (Sender<T>, Receiver<T>)`

Creates a new continuation channel, returning a sender-receiver pair.

`Sender<T>`

The sending half of a continuation channel. Allows synchronous code to send values to an asynchronous receiver.

send(item: T) - Sends a value through the channel (non-blocking)
is_cancelled() -> bool - Checks if the receiver has been dropped

`Receiver<T>`

The receiving half of a continuation channel. Provides asynchronous access to values sent through a Sender.

receive() -> ReceiveFuture<T> - Receives a single value from the channel
is_cancelled() -> bool - Checks if the sender has been dropped

Implements futures::Stream for ergonomic async iteration.

License

This project is licensed under the MIT or Apache-2.0 license, at your option.

continue_stream 0.1.1