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

//! # ice-threads
//!
//! ice-threads is a lightweight Thread Pool (Melter) implementation.
//!
//! User can enqueue Tasks (Ice) to be executed.
//!
//! Optionally, user can return a value that can be collected through a special handle (Bottle)
//! that is returned by the thread pool task enqueuing method.
//!
//! Tasks are put into the queue and eventually picked up by a task stealing thread (Heater) and
//! executed.
//!
//!
//! # Features
//!
//! * Very simple to use. [`Examples`].
//! * Very light crate with no dependencies.
//!
//! [`Examples`]: index.html#examples
//!
//!
//! # Examples
//!
//! Bare minimum:
//!
//! ```rust
//! use ice_threads::Melter;
//!
//! fn main() {
//!     let melter = Melter::new(1);
//!
//!     let s = melter.melt(|| {
//!         "Watch this task melt away!"
//!     }).open();
//!
//!     println!("{}", s);
//! }
//! ```
//!
//! Full control over result collection method:
//! ```rust
//! use ice_threads::Melter;
//!
//! fn main() {
//!     let melter = Melter::new(4);
//!     let mut bottles = Vec::new();
//!
//!     let src = "Water is collected synchronously in whatever order you want it to be";
//!     for chr in src.chars() {
//!         bottles.push(melter.melt(
//!             move || {
//!                 chr
//!             }
//!         ));
//!     }
//!
//!     let water = bottles.iter()
//!                         .map(|bottle| { bottle.open() })
//!                         .collect::<String>();
//!
//!     println!("{}", water);
//! }
//! ```
//!
//! More thorough example:
//! ```rust
//! use ice_threads::Melter;
//!
//!
//! fn main() {
//!     let melter = Melter::new(4);
//!     let mut bottles = Vec::new(); // Vec<Bottle<i32>>
//!
//!     for task_id in 0..8i32 { // add a type hint for Rust
//!         // Handle must always be used...
//!         let bottle = melter.melt(move || {
//!             use std::{thread::sleep, time::Duration};
//!
//!             // time consuming task
//!             sleep(Duration::from_secs(1));
//!
//!             println!("Finished task {}", task_id);
//!
//!             task_id
//!         });
//!
//!         // ...and not dropped without using it first
//!         bottles.push(bottle);
//!     }
//!
//!     // results don't need to be used but bottles must be opened
//!     for bottle in bottles {
//!         let result = bottle.open(); // blocking operation
//!         println!("Opened bottle, got: {}", result);
//!     }
//! }
//! ```
//!
//!
//! # Changelog
//!
//! ### v0.1.0
//! * Introduced [`Melter`] type (Thread Pool)
//! * Introduced [`Bottle`] type ("Future")
//!
//! [`Melter`]: struct.Melter.html
//! [`Bottle`]: struct.Bottle.html


mod bottle;
mod heater;
mod ice;
mod icebox;
mod meltable;
mod melter;



// public API
pub use bottle::Bottle;
pub use melter::Melter;


// private API
use heater::Heater;
use ice::Ice;
use icebox::IceBox;
use meltable::Meltable;