curfew 0.0.5

A deadline-aware fork-join model where multiple tasks run in parallel, but only those that finish before a specified absolute clock time are joined and their results collected.
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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

# curfew

[![Crates.io](https://img.shields.io/crates/v/curfew.svg)](https://crates.io/crates/curfew)
[![Documentation](https://docs.rs/curfew/badge.svg)](https://docs.rs/curfew)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`curfew` is a deadline-aware fork-join helper for Rust. It lets you spin up work across
multiple threads, set an **absolute** deadline (`std::time::Instant`), and collect only the
results that arrive on time. Late workers are skipped without attempting to cancel them,
so real-time sections of your application can keep moving.

## Installation

Add the crate to your Cargo manifest:

```toml
[dependencies]
curfew = "0.0.5"
```

Enable the optional `tokio` feature to work with async tasks powered by Tokio.

## Usage

### Joining a group of tasks before a deadline

```rust
use curfew::{DeadlineJoiner, TaskOutcome};
use std::thread;
use std::time::{Duration, Instant};

fn main() {
    let deadline = Instant::now() + Duration::from_millis(200);
    let mut joiner = DeadlineJoiner::new(deadline);

    for job in 0..4 {
        joiner.spawn(move || {
            // staggered work with different run times
            thread::sleep(Duration::from_millis(40 * job));
            job * 10
        });
    }

    let summary = joiner.join_ready();
    println!("completed before deadline: {}", summary.completed_count());
    println!("missed deadline: {}", summary.timed_out_count());

    for task in summary.completed {
        match task.outcome {
            TaskOutcome::Completed(value) => println!("task {} => {value}", task.task_id),
            TaskOutcome::Panicked(info) => println!("task {} panicked: {}", task.task_id, info),
        }
    }
}
```

### Joining an individual handle with a deadline

```rust
use curfew::{join_with_deadline, JoinOutcome, TaskOutcome};
use std::thread;
use std::time::{Duration, Instant};

fn main() {
    let handle = thread::spawn(|| {
        thread::sleep(Duration::from_millis(150));
        99
    });

    match join_with_deadline(handle, Instant::now() + Duration::from_millis(80)) {
        JoinOutcome::Completed(result) => match result.outcome {
            TaskOutcome::Completed(value) => println!("finished on time: {value}"),
            TaskOutcome::Panicked(info) => println!("task panicked: {info}"),
        },
        JoinOutcome::TimedOut(late) => {
            println!("missed deadline; waiting asynchronously for the late result");
            let result = late.wait();
            println!("late completion: {:?}", result.outcome);
        }
    }
}
```

### Async tasks with Tokio (`tokio` feature)

```rust
use curfew::{
    join_with_deadline_async, DeadlineJoinerAsync, JoinOutcomeAsync, TaskOutcome,
};
use std::time::{Duration, Instant};

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let deadline = Instant::now() + Duration::from_millis(120);
    let mut joiner = DeadlineJoinerAsync::new(deadline);

    for value in 0..3u32 {
        joiner.spawn(async move {
            tokio::time::sleep(Duration::from_millis(u64::from(30 * (value + 1))))
                .await;
            value
        });
    }

    let summary = joiner.join_ready().await;
    println!("async tasks finished on time: {}", summary.completed_count());

    let future = async {
        tokio::time::sleep(Duration::from_millis(200)).await;
        99
    };

    match join_with_deadline_async(future, Instant::now() + Duration::from_millis(60)).await {
        JoinOutcomeAsync::Completed(result) => match result.outcome {
            TaskOutcome::Completed(value) => println!("completed on time: {value}"),
            TaskOutcome::Panicked(info) => println!("task panicked: {info}"),
        },
        JoinOutcomeAsync::TimedOut(late) => {
            println!("future missed the deadline; waiting for late completion");
            let result = late.wait().await;
            println!("late outcome: {:?}", result.outcome);
        }
    }
}
```

## API Highlights

- `DeadlineJoiner` spawns tasks, tracks their start/finish instants, and only returns
  results that beat the deadline.
- `join_with_deadline` wraps a single `JoinHandle`, returning a `LateTask` so callers can
  optionally await the late result later.
- Enable the `tokio` feature for async siblings `DeadlineJoinerAsync` and
  `join_with_deadline_async` with the same semantics.
- Rich metadata via `TaskResult`, `TaskOutcome`, and `TimedOutTask` for diagnostics and
  logging.

## Limitations

- Tasks are never forcefully terminated. Anything that misses the deadline continues
  running in the background until it completes naturally.
- Deadlines rely on the monotonic `Instant` clock. System clock adjustments do not
  influence scheduling, but very long sleeps may still drift.

## Examples

Run the bundled examples with `cargo run --example basic` or see `examples/` for more
scenarios (enable `--features tokio` for `async_example`).

## Development

See [_dev/PRD.md](./_dev/PRD.md) for the full product specification and
[CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

This project is licensed under MIT. See [LICENSE](LICENSE) for details.