atap 0.1.0

Threadsafe futureless async runtime for macOS
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

//! # Runtime Builder
//! The chain a runtime is started through when the defaults don't
//! suit

use crate::{
    modules::{errors::RuntimeError, tuning::Tuning},
    runtime::Runtime,
};

/// The sizes a runtime is about to start with
///
/// ## Behaviour
/// Nothing happens until `init` is called. Every setting left
/// alone keeps the value a plain `Runtime::init` uses
///
/// ```no_run
/// use atap::{Runtime, RuntimeError};
///
/// # fn main() -> Result<(), RuntimeError> {
/// Runtime::builder()
///     .workers_per_core(2)
///     .sleep_threads_per_core(4)
///     .worker_stack(2 * 1024 * 1024)
///     .init()?;
/// # Ok(())
/// # }
/// ```
pub struct RuntimeBuilder {
    /// What the pool is given once `init` is called
    tuning: Tuning,
}

impl RuntimeBuilder {
    /// A builder holding the defaults
    pub(crate) const fn new() -> Self {
        Self {
            tuning: Tuning::new(),
        }
    }

    /// Sets the workers the pool settles around, per core
    ///
    /// A target rather than a limit: the pool passes it on overload
    /// or real need, and never goes below one worker per core
    pub fn workers_per_core(mut self, count: usize) -> Self {
        self.tuning.set_workers_per_core(count);

        self
    }

    /// Sets the sleep threads the pool settles around, per core
    ///
    /// Sleep threads run the tasks that block, so this is the depth
    /// of blocking work that runs at once
    pub fn sleep_threads_per_core(mut self, count: usize) -> Self {
        self.tuning.set_sleep_threads_per_core(count);

        self
    }

    /// Sets the stack reserved for each worker thread
    pub fn worker_stack(mut self, bytes: usize) -> Self {
        self.tuning.set_worker_stack(bytes);

        self
    }

    /// Starts the runtime with these sizes
    ///
    /// ## Returns
    /// `BadArgument` for a count of zero or a stack too small for a
    /// thread, and `AlreadyInit` when a runtime is already running,
    /// which leaves the sizes as they are
    ///
    /// After a `shutdown` these sizes replace the ones before them
    pub fn init(self) -> Result<(), RuntimeError> {
        self.tuning.check()?;

        Runtime::init_with(self.tuning)
    }
}

impl Default for RuntimeBuilder {
    fn default() -> Self {
        Self::new()
    }
}