ice_threads/
lib.rs

1//! # ice-threads
2//!
3//! ice-threads is a lightweight Thread Pool (Melter) implementation.
4//!
5//! User can enqueue Tasks (Ice) to be executed.
6//!
7//! Optionally, user can return a value that can be collected through a special handle (Bottle)
8//! that is returned by the thread pool task enqueuing method.
9//!
10//! Tasks are put into the queue and eventually picked up by a task stealing thread (Heater) and
11//! executed.
12//!
13//!
14//! # Features
15//!
16//! * Very simple to use. [`Examples`].
17//! * Very light crate with no dependencies.
18//!
19//! [`Examples`]: index.html#examples
20//!
21//!
22//! # Examples
23//!
24//! Bare minimum:
25//!
26//! ```rust
27//! use ice_threads::Melter;
28//!
29//! fn main() {
30//!     let melter = Melter::new(1);
31//!
32//!     let s = melter.melt(|| {
33//!         "Watch this task melt away!"
34//!     }).open();
35//!
36//!     println!("{}", s);
37//! }
38//! ```
39//!
40//! Full control over result collection method:
41//! ```rust
42//! use ice_threads::Melter;
43//!
44//! fn main() {
45//!     let melter = Melter::new(4);
46//!     let mut bottles = Vec::new();
47//!
48//!     let src = "Water is collected synchronously in whatever order you want it to be";
49//!     for chr in src.chars() {
50//!         bottles.push(melter.melt(
51//!             move || {
52//!                 chr
53//!             }
54//!         ));
55//!     }
56//!
57//!     let water = bottles.iter()
58//!                         .map(|bottle| { bottle.open() })
59//!                         .collect::<String>();
60//!
61//!     println!("{}", water);
62//! }
63//! ```
64//!
65//! More thorough example:
66//! ```rust
67//! use ice_threads::Melter;
68//!
69//!
70//! fn main() {
71//!     let melter = Melter::new(4);
72//!     let mut bottles = Vec::new(); // Vec<Bottle<i32>>
73//!
74//!     for task_id in 0..8i32 { // add a type hint for Rust
75//!         // Handle must always be used...
76//!         let bottle = melter.melt(move || {
77//!             use std::{thread::sleep, time::Duration};
78//!
79//!             // time consuming task
80//!             sleep(Duration::from_secs(1));
81//!
82//!             println!("Finished task {}", task_id);
83//!
84//!             task_id
85//!         });
86//!
87//!         // ...and not dropped without using it first
88//!         bottles.push(bottle);
89//!     }
90//!
91//!     // results don't need to be used but bottles must be opened
92//!     for bottle in bottles {
93//!         let result = bottle.open(); // blocking operation
94//!         println!("Opened bottle, got: {}", result);
95//!     }
96//! }
97//! ```
98//!
99//!
100//! # Changelog
101//!
102//! ### v0.1.0
103//! * Introduced [`Melter`] type (Thread Pool)
104//! * Introduced [`Bottle`] type ("Future")
105//!
106//! [`Melter`]: struct.Melter.html
107//! [`Bottle`]: struct.Bottle.html
108
109
110mod bottle;
111mod heater;
112mod ice;
113mod icebox;
114mod meltable;
115mod melter;
116
117
118
119// public API
120pub use bottle::Bottle;
121pub use melter::Melter;
122
123
124// private API
125use heater::Heater;
126use ice::Ice;
127use icebox::IceBox;
128use meltable::Meltable;
ice_threads/lib.rs

ice_threads/
lib.rs
