sack 0.1.0

A lock-free data structure for adding & retrieving items
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

# sack

[![crates.io](https://img.shields.io/crates/v/sack.svg)](https://crates.io/crates/sack)
[![docs.rs](https://docs.rs/sack/badge.svg)](https://docs.rs/sack)

A lock-free sack data structure and a `WakerSet` for waking multiple tasks at once.

## Overview

This crate provides two data structures:

- `Sack<T>`: A concurrent, lock-free sack that supports adding and draining items.
- `WakerSet`: A set of wakers that can be woken all at once.

`Sack<T>` is implemented as a lock-free, singly-linked list, and `WakerSet` is a wrapper around a `Sack<Waker>`.

Generally this provides better performance than `Mutex<Vec<T>>` for small numbers of entries. However it can vary depending on the specific use case and access patterns. Always benchmark your code to find the best solution for your particular scenario.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
sack = "0.1.0"
```

### Sack

Here is an example of how to use `Sack` in a multi-producer, single-consumer scenario:

```rust
use sack::Sack;
use std::sync::Arc;
use std::thread;

let sack = Arc::new(Sack::new());

// Spawn a producer thread.
let producer = {
    let sack = Arc::clone(&sack);
    thread::spawn(move || {
        for i in 0..10 {
            sack.add(i);
        }
    })
};

// Wait for the producer to finish.
producer.join().unwrap();

// Drain the sack and collect the items.
let mut items: Vec<_> = sack.drain().collect();
items.sort();

assert_eq!(items, (0..10).collect::<Vec<_>>());
```

### WakerSet

Here is an example of how to use `WakerSet` to wake up multiple tasks:

```rust
use sack::WakerSet;
use std::sync::Arc;
use std::task::{Wake, Waker};

// Create a new WakeSet.
let wake_set = Arc::new(WakerSet::new());

// Add the waker to the set.
wake_set.add_by_ref(Waker::noop());

// Wake all wakers in the set.
assert_eq!(wake_set.wake_all(), 1);
```

## API

The API is documented on [docs.rs](https://docs.rs/sack).

## License

This project is licensed under the MIT license.