wavelet 0.1.2

High-performance graph-based stream processing runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Wavelet

A high-performance, graph-based stream processing runtime for Rust that delivers deterministic execution with zero-cost
abstractions.

![Wavelet](wavelet.png)

## Overview

Wavelet is designed for applications that need predictable, low-latency stream processing without the overhead of async
runtimes or actor systems. Built around a computation graph where nodes represent stream processors and edges define
data dependencies, wavelet provides:

- **Deterministic execution** - Same inputs always produce the same execution order
- **Dependency-ordered processing** - Guaranteed that parent nodes are always processed before their children
- **Event integration** - Unified I/O, timer, and yield event handling
- **Dependency injection** - Build-time configuration for different environments

## Quick Start

Add wavelet to your `Cargo.toml`:

```toml
[dependencies]
wavelet = "0.1"
```

Create a simple stream processing graph:

```rust
use wavelet::prelude::*;
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = Runtime::builder()
        .with_clock(PrecisionClock::new())
        .with_mode(Sleep::new(Duration::from_millis(1)))
        .build()?;

    // Create a data source
    let source = NodeBuilder::new(0u64)
        .on_init(|executor, _, idx| {
            executor.yield_driver().yield_now(idx);
        })
        .build(runtime.executor(), |counter, _ctx| {
            *counter += 1;
            println!("Source: {}", counter);
            Control::Broadcast
        });

    // Create a processor that reacts to the source
    let _processor = NodeBuilder::new(String::new())
        .triggered_by(&source)
        .build(runtime.executor(), |state, _ctx| {
            *state = format!("Processed: {}", source.borrow());
            println!("{}", state);
            Control::Unchanged
        });

    // Run the graph
    runtime.run_forever();
}
```

## Architecture

### Core Concepts

- **Nodes**: Stateful stream processors that transform data
- **Relationships**: Define execution dependencies (`Trigger` vs `Observe`)
- **Cooperative Scheduling**: Nodes yield control after processing
- **Event System**: I/O, timer, and yield events drive execution

### Key Components

```rust, ignore
// Build a computation graph
let processor = NodeBuilder::new(ProcessorState::new())
    .triggered_by(&data_source)     // Execute when source changes
    .observer_of(&config_node)      // Read config but don't auto-execute
    .with_name("processor".into())
    .build(&mut executor, |state, ctx| {
        // Process data with mutable access to state
        state.process(data_source.borrow().latest_data());
        Control::Broadcast  // Notify downstream nodes
    });
```

## Features

Wavelet uses Cargo features to enable different functionality:

- `runtime` (default) - Core execution engine
- `factories` - Dependency injection for build-time configuration
- `full` - All features enabled

```toml
[dependencies]
wavelet = { version = "0.1", features = ["full"] }
```

### Dependency Injection with Factories

Configure different implementations for different environments:

```rust, ignore
use wavelet::factories::*;

let data_source = match environment {
Environment::Production => KeyedFactory::default ()
.attach( | executor, symbol| create_live_feed(executor, symbol)),
Environment::Test => KeyedFactory::default ()
.attach( | executor, symbol| create_mock_feed(executor, symbol)),
};

// Same graph construction code works with any configured factory
let feed = data_source.get( & mut executor, "EURUSD".to_string());
```

## Use Cases

Wavelet excels in domains requiring deterministic, low-latency processing:

- **Financial Systems** - Trading engines, risk management, market data processing
- **Real-time Analytics** - Live dashboards, alerting, stream aggregation
- **IoT Processing** - Sensor data, device management, edge computing
- **Protocol Handling** - Stateful network protocols, message parsing

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License ([LICENSE](LICENSE))