arty 0.5.0

Single-threaded, thread-aware application runtime.
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

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

use crate::runtime::Runtime;
use crate::runtime::dispatch::DispatcherClient;
use crate::task::{Builtins, Scheduler};

/// A handle for requesting runtime shutdown.
///
/// Create this handle with `RuntimeOperations::from(&runtime)` or
/// `RuntimeOperations::from(&builtins)`.
/// It can be cloned and used from any thread without keeping the runtime alive
/// or retaining an association with the task's worker.
///
/// [`request_stop`](Self::request_stop) initiates shutdown without waiting.
#[derive(Debug, Clone)]
pub struct RuntimeOperations {
    dispatcher: DispatcherClient,
}

impl RuntimeOperations {
    /// Requests shutdown without blocking the calling thread.
    ///
    /// May be called repeatedly from any thread. Pending tasks are cancelled,
    /// and new submissions receive [`JoinError`](crate::task::JoinError).
    /// Running blocking callbacks are allowed to finish. The owner remains
    /// responsible for waiting for shutdown when it is stopped or dropped.
    ///
    /// # Examples
    ///
    /// ```
    /// use arty::runtime::{Runtime, RuntimeOperations};
    ///
    /// let runtime = Runtime::new()?;
    /// let operations = RuntimeOperations::from(&runtime);
    /// operations.request_stop();
    /// runtime.stop()?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg_attr(test, mutants::skip)] // It is impractical to test for "stuff not happening", so mutating this easily leads to timeouts.
    pub fn request_stop(&self) {
        Scheduler::begin_current_executor_shutdown(&self.dispatcher);
        self.dispatcher.stop();
    }
}

impl From<&Builtins> for RuntimeOperations {
    fn from(builtins: &Builtins) -> Self {
        Self {
            dispatcher: builtins.scheduler.dispatcher.clone(),
        }
    }
}

impl From<&Runtime> for RuntimeOperations {
    fn from(runtime: &Runtime) -> Self {
        Self {
            dispatcher: runtime.scheduler().dispatcher.clone(),
        }
    }
}