announcement

A runtime-agnostic oneshot broadcast channel for Rust.

Broadcast a value once to multiple listeners with minimal overhead and zero data duplication when used with Arc<T>.

Features

• Simple API - Create, announce, listen
• Fast - Built on Arc<OnceLock> and event-listener
• Runtime-agnostic - Works with tokio, async-std, smol, or any executor
• Type-safe - Can only announce once, listeners are cloneable
• Lightweight - Minimal dependencies
• Cancel-safe - All async operations are cancel-safe

Performance

Sub-microsecond operations with linear scaling

• Channel creation: ~50ns
• Listener creation: ~10ns per listener
• Announcement: ~60ns + 11ns per listener
• Lock-free retrieval: ~0.6ns (sub-nanosecond)

Critical recommendation: Use Arc<T> for types >64 bytes or with 3+ listeners for dramatic performance gains (up to 600x faster for large types).

📊 Full Performance Analysis → - Comprehensive benchmarks, scaling analysis, and optimization guide

Installation

Add this to your Cargo.toml:

[dependencies]
announcement = "0.1"

For tracing support:

[dependencies]
announcement = { version = "0.1", features = ["tracing"] }

For blocking-only (no std):

[dependencies]
announcement = { version = "0.1", default-features = false }

Quick Start

use announcement::Announcement;

#[tokio::main]
async fn main() {
    // Create announcement channel
    let (announcer, announcement) = Announcement::new();

    // Create multiple listeners
    let listener1 = announcement.listener();
    let listener2 = announcement.listener();

    // Spawn tasks that wait for the announcement
    tokio::spawn(async move {
        let value = listener1.listen().await;
        println!("Listener 1 received: {}", value);
    });

    tokio::spawn(async move {
        let value = listener2.listen().await;
        println!("Listener 2 received: {}", value);
    });

    // Announce to all listeners at once
    announcer.announce(42).unwrap();
}

Learning Guide

The examples/ directory contains a progressive learning guide. Read these in order:

1. 01_basic_usage.rs - Start here! Creating channels, announcing, try_listen()
2. 02_async_listening.rs - Async operations with listen().await
3. 03_multiple_listeners.rs - Broadcasting to multiple listeners
4. 04_efficient_broadcasting.rs - Using Arc for efficiency
5. 05_blocking_operations.rs - Blocking operations and deadlock prevention

Each example is heavily documented with explanations, tips, and best practices. They're meant to be read and learned from, not just run.

Advanced Examples

After completing the guide, check out these real-world patterns:

• shutdown.rs - Graceful shutdown signal pattern
• config_broadcast.rs - Configuration broadcast to workers
• lazy_init.rs - Lazy resource initialization pattern

Usage Examples

Shutdown Signal Pattern

Coordinate graceful shutdown of multiple worker tasks:

use announcement::Announcement;

#[tokio::main]
async fn main() {
    let (shutdown_tx, shutdown_rx) = Announcement::new();

    // Spawn workers with shutdown listeners
    let worker = tokio::spawn({
        let shutdown = shutdown_rx.listener();
        async move {
            loop {
                tokio::select! {
                    _ = shutdown.listen() => {
                        println!("Shutting down gracefully...");
                        break;
                    }
                    _ = do_work() => {}
                }
            }
        }
    });

    // Later: broadcast shutdown signal
    shutdown_tx.announce(()).unwrap();
    worker.await.unwrap();
}

async fn do_work() {
    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
}

Configuration Broadcast

Share initialized configuration to multiple workers using Arc for efficiency:

use announcement::Announcement;
use std::sync::Arc;

#[derive(Clone, Debug)]
struct Config {
    database_url: String,
    api_key: String,
}

#[tokio::main]
async fn main() {
    let (config_tx, config_rx) = Announcement::new();

    // Workers can start before config is ready
    let worker = tokio::spawn({
        let config_listener = config_rx.listener();
        async move {
            // Wait for config to be ready
            let config = config_listener.listen().await;
            println!("Worker received config: {:?}", config);
        }
    });

    // Initialize config (takes time)
    let config = Arc::new(Config {
        database_url: "postgresql://localhost/db".to_string(),
        api_key: "secret".to_string(),
    });

    // Broadcast to all workers (Arc is cloned, not the data)
    config_tx.announce(config).unwrap();

    worker.await.unwrap();
}

Lazy Initialization

Signal when a resource is ready:

use announcement::Announcement;
use std::sync::Arc;

struct Database { /* ... */ }

impl Database {
    async fn connect() -> Self {
        // Expensive initialization
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        Database { /* ... */ }
    }
}

#[tokio::main]
async fn main() {
    let (db_tx, db_rx) = Announcement::new();

    // Services wait for database
    let api_service = tokio::spawn({
        let db = db_rx.listener();
        async move {
            let db = db.listen().await;
            // Use database
        }
    });

    // Initialize database
    let db = Arc::new(Database::connect().await);
    db_tx.announce(db).unwrap();

    api_service.await.unwrap();
}

Non-blocking Check

Use try_listen() to check without waiting:

use announcement::Announcement;

let (announcer, announcement) = Announcement::new();
let listener = announcement.listener();

// Check if value is ready
if let Some(value) = listener.try_listen() {
    println!("Already announced: {}", value);
} else {
    println!("Not announced yet");
}

announcer.announce(42).unwrap();

// Now it's available
assert_eq!(listener.try_listen(), Some(42));

Clone vs Arc: When to Use Each

Announcement<T> requires T: Clone. Each listener clones the value.

Use Direct Values

✓ For small types (< 16 bytes):

Announcement::<i32>::new()
Announcement::<(u64, u64)>::new()

✓ For Copy types:

Announcement::<f64>::new()

✓ For 1-2 listeners (clone cost amortized)

Use Arc for Efficiency

✓ For large types:

Announcement::<Arc<Vec<u8>>>::new()  // Instead of Vec<u8>

✓ For expensive clones:

Announcement::<Arc<Config>>::new()  // Config has String, Vec, HashMap

✓ For many listeners (3+):

let (tx, announcement) = Announcement::<Arc<Data>>::new();
// Create 1000 listeners - only 1 Data allocation!

Memory Savings Example

Broadcasting 1MB data to 100 listeners:

• Without Arc: 100 MB (100 allocations)
• With Arc: 1 MB (1 allocation)
• Savings: 99 MB, 200,000x faster

See example 04 for detailed explanation.

Use Cases

• Shutdown signals - Notify all tasks to shut down gracefully
• Configuration broadcast - Share initialized config to all workers
• Lazy initialization - Signal when a resource is ready (database, cache, etc.)
• Event fanout - Broadcast a one-time event to multiple subscribers
• Barrier synchronization - Wait for initialization to complete
• State transitions - Signal when application reaches a certain state

Performance

Benchmarked on AMD Ryzen 7 7840U (8C/16T), 64GB RAM, Framework 13 laptop

Core Operations

Clone vs Arc Comparison

For large types (1MB) with 100 listeners:

Rule of thumb: Use Arc<T> for:

• Types > 8 bytes with multiple listeners
• Expensive-to-clone types (Vec, String, HashMap)

Scalability

• 1,000 listeners: ~15µs announce, ~8µs retrieve all
• 10,000 listeners: ~150µs announce, ~80µs retrieve all
• 100,000 listeners: ~1.5ms announce, ~800µs retrieve all

Linear scaling O(N) for wakeup, constant O(1) for retrieval.

Testing

Run tests (recommended - faster):

cargo nextest run

Or with standard test runner:

cargo test

Test Coverage: 507+ tests covering:

• All primitive types
• Collections, smart pointers, trait objects
• Edge cases (ZST, 1MB+ types, recursive structures)
• Concurrency (1000+ threads)
• Race conditions (10,000 iterations)
• Cross-runtime compatibility (tokio, async-std, smol)
• Property-based testing with proptest

Comparison to Alternatives

vs tokio::sync::broadcast

Use announcement when:

• You need to broadcast once (shutdown, config, initialization)
• You want runtime independence
• You want simpler semantics

Use tokio::sync::broadcast when:

• You need to send multiple values
• You're already using tokio
• You need bounded buffering

vs tokio::sync::oneshot

Use announcement when:

• You need 1-to-many communication
• You want to create listeners dynamically

Use tokio::sync::oneshot when:

• You only need 1-to-1 communication
• You're using tokio

vs Manual Arc<OnceLock> + Event

announcement provides a safe, ergonomic wrapper around this pattern with:

• Type-safe oneshot semantics (can't announce twice)
• Proper TOCTOU protection in async contexts
• Clear ownership model
• Documented best practices

Contributing

Contributions are welcome! Please see CODE_OF_CONDUCT.md for community guidelines.

License

This project is licensed under the MIT License.

Copyright (c) 2025 Stephen Waits steve@waits.net

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See Also

• API Documentation
• Examples
• Changelog