rust-tokio-supervisor 0.1.4

A Rust tokio supervisor with declarative task supervision, restart policy, shutdown coordination, and observability.
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

//! Sidecar role context wrapper.
//!
//! The wrapper keeps sidecar code focused on readiness, heartbeat, primary
//! child visibility, and shutdown observation without exposing the full runtime
//! task context.

use crate::id::types::{ChildId, SupervisorPath};
use crate::task::context::TaskContext;

/// Narrow context passed to a sidecar role.
#[derive(Debug, Clone)]
pub struct SidecarContext {
    /// Runtime task context hidden behind the sidecar-specific API.
    inner: TaskContext,
    /// Stable child identifier for the primary child this sidecar follows.
    primary_child_id: ChildId,
}

impl SidecarContext {
    /// Creates a sidecar context from a runtime task context.
    ///
    /// # Arguments
    ///
    /// - `inner`: Runtime context for one sidecar child_start_count.
    /// - `primary_child_id`: Stable child identifier for the primary child.
    ///
    /// # Returns
    ///
    /// Returns a sidecar-specific context wrapper.
    ///
    /// # Examples
    ///
    /// ```
    /// let (task_context, _heartbeat) = rust_supervisor::task::context::TaskContext::new(
    ///     rust_supervisor::id::types::ChildId::new("sidecar"),
    ///     rust_supervisor::id::types::SupervisorPath::root().join("sidecar"),
    ///     rust_supervisor::id::types::Generation::initial(),
    ///     rust_supervisor::id::types::ChildStartCount::first(),
    /// );
    /// let sidecar_context = rust_supervisor::role::context::sidecar::SidecarContext::new(
    ///     task_context,
    ///     rust_supervisor::id::types::ChildId::new("primary"),
    /// );
    /// assert_eq!(sidecar_context.primary_id().value, "primary");
    /// ```
    pub fn new(inner: TaskContext, primary_child_id: ChildId) -> Self {
        Self {
            inner,
            primary_child_id,
        }
    }

    /// Reports that the sidecar is ready.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// This function does not return a value.
    ///
    /// # Examples
    ///
    /// ```
    /// let (task_context, _heartbeat) = rust_supervisor::task::context::TaskContext::new(
    ///     rust_supervisor::id::types::ChildId::new("sidecar"),
    ///     rust_supervisor::id::types::SupervisorPath::root().join("sidecar"),
    ///     rust_supervisor::id::types::Generation::initial(),
    ///     rust_supervisor::id::types::ChildStartCount::first(),
    /// );
    /// let sidecar_context = rust_supervisor::role::context::sidecar::SidecarContext::new(
    ///     task_context,
    ///     rust_supervisor::id::types::ChildId::new("primary"),
    /// );
    /// sidecar_context.ready();
    /// ```
    pub fn ready(&self) {
        self.inner.mark_ready();
    }

    /// Emits a sidecar heartbeat.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// This function does not return a value.
    pub fn heartbeat(&self) {
        self.inner.heartbeat();
    }

    /// Returns the primary child identifier linked to this sidecar.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// Returns the primary child identifier owned by the sidecar context.
    pub fn primary_id(&self) -> &ChildId {
        &self.primary_child_id
    }

    /// Returns whether shutdown has been requested.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// Returns `true` when runtime cancellation has been requested.
    pub fn is_shutdown_requested(&self) -> bool {
        self.inner.is_cancelled()
    }

    /// Waits until shutdown has been requested.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// Returns after the runtime cancellation token has been cancelled.
    pub async fn wait_shutdown(&self) {
        self.inner.cancellation_token().cancelled().await;
    }

    /// Returns the stable sidecar child identifier.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// Returns the child identifier owned by the runtime context.
    pub fn child_id(&self) -> &ChildId {
        &self.inner.child_id
    }

    /// Returns the sidecar path in the supervisor tree.
    ///
    /// # Arguments
    ///
    /// This function has no arguments.
    ///
    /// # Returns
    ///
    /// Returns the supervisor tree path owned by the runtime context.
    pub fn path(&self) -> &SupervisorPath {
        &self.inner.path
    }
}