wpool 0.1.2

A thread pool that limits the number of tasks executing concurrently, without restricting how many tasks can be queued.
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

# wpool

[![Crates.io](https://img.shields.io/crates/v/wpool.svg)](https://crates.io/crates/wpool)

A thread pool that limits the number of tasks executing concurrently, without restricting how many tasks can be queued. Submitting tasks is non-blocking, so you can enqueue any number of tasks without waiting.

This library is essentially a port of [`workerpool`](https://github.com/gammazero/workerpool), an amazing Go library.

## Pool with only worker maximum

```rust
// At most 10 workers can run at once.
let max_workers = 10;

let pool = WPool::new(max_workers);

// Submit as many functions as you'd like.
pool.submit(|| {
  // Do some work.
});
pool.submit(|| {
  // Do more work.
});

// Block until all workers are done working and
// the waiting queue has been processed.
pool.stop_wait();
```

## Pool with both worker maximum and worker minimum

`min_workers` defines (up to) the minimum number of worker threads that should always stay alive, even when the pool is idle.

**NOTE**: _We do not 'pre-spawn' workers!_ Meaning, if you set `min_workers = 3` but your pool only ever creates 2 workers, then only 2 workers will ever exist (and should always be alive).

```rust
// At most 10 workers can run at once.
let max_workers = 10;
// At minimum up to 3 workers should always exist.
let min_workers = 3;

let pool = WPool::new_with_min(max_workers, min_workers);

// Submit as many functions as you'd like.
pool.submit(|| {
  // Do some work.
});
pool.submit(|| {
  // Do more work.
});

// Block until all workers are done working and
// the waiting queue has been processed.
pool.stop_wait();
```

## Get results out of worker task

```rust
let max_workers = 2;
let wp = WPool::new(max_workers);
let (tx, rx) = mpsc::sync_channel::<u8>(0);

let tx_clone = tx.clone();
wp.submit(move || {
    //
    // Do work here.
    //
    thread::sleep(Duration::from_millis(500));
    //
    let result_from_doing_work = 69;
    //

    if let Err(e) = tx_clone.send(result_from_doing_work) {
        println!("error sending results to main thread from worker! : Error={e:?}");
    }
    println!("success! sent results from worker to main!");
});

// Pause until we get our result.
//
// (Note: pausing is not necessary in this example,
// as our channel can act as a pseudo pauser)
//
// If we were using an unbounded channel, we may want
// to use pause in order to wait
// for the result of any running task (like if we need
// to use the result elsewhere).
//
// wp.pause();

match rx.recv() {
    Ok(result) => assert_eq!(result, 69),
    Err(_) => {
        panic!("expected this not to fail and let us receive results from worker via channel.")
    }
};

wp.stop_wait();
```

## Use with `Pacer`

Read more about `Pacer` [here](https://docs.rs/wpool/latest/wpool/pacer/index.html)

```rust
use wpool::pacer::Pacer;

let at_pace = Duration::from_secs(1);
let pacer = Pacer::new(at_pace);
let counter = Arc::new(AtomicUsize::new(0));

let c = Arc::clone(&counter);
let paced_fn = pacer.pace(move || {
    println!("Hello, world!");
    c.fetch_add(1, Ordering::SeqCst);
});

let max_workers = 5;
let wp = WPool::new(max_workers);

let wp_paced_fn = Arc::clone(&paced_fn);
wp.submit(move || { wp_paced_fn() });
wp.stop_wait();
assert_eq!(counter.load(Ordering::SeqCst), 1);
```