compio-executor 0.1.4

Executor for compio
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

//! No-op stand-ins used when the `console` feature is disabled.

use std::marker::PhantomData;

/// Metadata of a spawned task, reported to the console.
///
/// Zero-sized and inert unless the `console` feature is enabled.
#[derive(Debug, Clone, Copy)]
pub struct SpawnMeta;

impl SpawnMeta {
    /// Capture the location of the caller.
    ///
    /// Discards it. The spawns that call this stay `#[track_caller]` either
    /// way: a feature of this crate cannot reach the wrappers in the crates
    /// that depend on it, so gating them on one of their own would attribute
    /// every task to compio itself in a build that enables only this one. The
    /// implicit argument is dead here, and mostly optimised away.
    #[inline(always)]
    pub fn capture() -> Self {
        Self
    }

    /// Name the task, which the console displays in a column of its own.
    #[inline(always)]
    pub fn named(self, _name: &'static str) -> Self {
        self
    }

    /// Do not report the task to the console at all.
    #[inline(always)]
    pub fn untracked() -> Self {
        Self
    }
}

/// The guard returned by [`TaskSpan::enter`].
///
/// The enabled variant measures the busy time of a task as the time its guard
/// is alive, so dropping it right away is a bug that this makes visible in both
/// configurations. It borrows the span for the same reason: the enabled guard
/// does, and code that compiles without the feature has to compile with it.
#[must_use = "the task span is exited as soon as this is dropped"]
pub(crate) struct Entered<'a>(PhantomData<&'a TaskSpan>);

/// The guard [`TaskSpan::enter`] returns, named the same in both variants so
/// that the parity assertions can reach it.
pub(crate) type EnterGuard<'a> = Entered<'a>;

/// The `runtime.spawn` span of a task.
#[derive(Debug)]
pub(crate) struct TaskSpan;

impl TaskSpan {
    #[inline(always)]
    #[expect(
        clippy::extra_unused_type_parameters,
        reason = "mirrors the enabled variant, which records the future's size"
    )]
    pub(crate) fn new<F>(_meta: SpawnMeta) -> Self {
        Self
    }

    #[inline(always)]
    pub(crate) fn enter(&self) -> EnterGuard<'_> {
        Entered(PhantomData)
    }

    #[inline(always)]
    pub(crate) fn waker_op(&self, _op: super::WakerOp) {}
}

/// Instrument a closure about to be handed to the blocking pool, so that it
/// shows up as a blocking task in the console.
///
/// This is a no-op unless the `console` feature is enabled.
///
/// Plumbing for `compio-runtime`, not covered by this crate's semver.
#[doc(hidden)]
#[inline(always)]
pub fn instrument_blocking<T, F: FnOnce() -> T>(_meta: SpawnMeta, f: F) -> impl FnOnce() -> T {
    f
}

/// Instrument a future blocked on by the runtime, so that it shows up as a
/// task in the console.
///
/// This is a no-op unless the `console` feature is enabled.
///
/// Plumbing for `compio-runtime`, not covered by this crate's semver.
#[doc(hidden)]
#[inline(always)]
pub fn instrument_block_on<F: Future>(_meta: SpawnMeta, fut: F) -> impl Future<Output = F::Output> {
    fut
}

/// Instrument a future executed by a compatibility layer, so that it shows up
/// as a task in the console.
///
/// This is a no-op unless the `console` feature is enabled.
///
/// Plumbing for `compio-compat`, not covered by this crate's semver.
#[doc(hidden)]
#[inline(always)]
pub fn instrument_execute<F: Future>(_meta: SpawnMeta, fut: F) -> impl Future<Output = F::Output> {
    fut
}