rust_supervisor/role/context/
service.rs

1//! Service role context wrapper.
2//!
3//! The wrapper keeps service code focused on readiness, heartbeat, and
4//! shutdown observation without exposing the full runtime task context.
5
6use crate::id::types::{ChildId, SupervisorPath};
7use crate::task::context::TaskContext;
8
9/// Narrow context passed to a service role.
10#[derive(Debug, Clone)]
11pub struct ServiceContext {
12    /// Runtime task context hidden behind the service-specific API.
13    inner: TaskContext,
14}
15
16impl ServiceContext {
17    /// Creates a service context from a runtime task context.
18    ///
19    /// # Arguments
20    ///
21    /// - `inner`: Runtime context for one service child_start_count.
22    ///
23    /// # Returns
24    ///
25    /// Returns a service-specific context wrapper.
26    ///
27    /// # Examples
28    ///
29    /// ```
30    /// let (task_context, _heartbeat) = rust_supervisor::task::context::TaskContext::new(
31    ///     rust_supervisor::id::types::ChildId::new("service"),
32    ///     rust_supervisor::id::types::SupervisorPath::root().join("service"),
33    ///     rust_supervisor::id::types::Generation::initial(),
34    ///     rust_supervisor::id::types::ChildStartCount::first(),
35    /// );
36    /// let service_context = rust_supervisor::role::context::service::ServiceContext::new(
37    ///     task_context,
38    /// );
39    /// assert!(!service_context.is_shutdown_requested());
40    /// ```
41    pub fn new(inner: TaskContext) -> Self {
42        Self { inner }
43    }
44
45    /// Reports that the service is ready.
46    ///
47    /// # Arguments
48    ///
49    /// This function has no arguments.
50    ///
51    /// # Returns
52    ///
53    /// This function does not return a value.
54    ///
55    /// # Examples
56    ///
57    /// ```
58    /// let (task_context, _heartbeat) = rust_supervisor::task::context::TaskContext::new(
59    ///     rust_supervisor::id::types::ChildId::new("service"),
60    ///     rust_supervisor::id::types::SupervisorPath::root().join("service"),
61    ///     rust_supervisor::id::types::Generation::initial(),
62    ///     rust_supervisor::id::types::ChildStartCount::first(),
63    /// );
64    /// let service_context = rust_supervisor::role::context::service::ServiceContext::new(
65    ///     task_context,
66    /// );
67    /// service_context.ready();
68    /// ```
69    pub fn ready(&self) {
70        self.inner.mark_ready();
71    }
72
73    /// Emits a service heartbeat.
74    ///
75    /// # Arguments
76    ///
77    /// This function has no arguments.
78    ///
79    /// # Returns
80    ///
81    /// This function does not return a value.
82    pub fn heartbeat(&self) {
83        self.inner.heartbeat();
84    }
85
86    /// Returns whether shutdown has been requested.
87    ///
88    /// # Arguments
89    ///
90    /// This function has no arguments.
91    ///
92    /// # Returns
93    ///
94    /// Returns `true` when runtime cancellation has been requested.
95    pub fn is_shutdown_requested(&self) -> bool {
96        self.inner.is_cancelled()
97    }
98
99    /// Waits until shutdown has been requested.
100    ///
101    /// # Arguments
102    ///
103    /// This function has no arguments.
104    ///
105    /// # Returns
106    ///
107    /// Returns after the runtime cancellation token has been cancelled.
108    pub async fn wait_shutdown(&self) {
109        self.inner.cancellation_token().cancelled().await;
110    }
111
112    /// Returns the stable service child identifier.
113    ///
114    /// # Arguments
115    ///
116    /// This function has no arguments.
117    ///
118    /// # Returns
119    ///
120    /// Returns the child identifier owned by the runtime context.
121    pub fn child_id(&self) -> &ChildId {
122        &self.inner.child_id
123    }
124
125    /// Returns the service path in the supervisor tree.
126    ///
127    /// # Arguments
128    ///
129    /// This function has no arguments.
130    ///
131    /// # Returns
132    ///
133    /// Returns the supervisor tree path owned by the runtime context.
134    pub fn path(&self) -> &SupervisorPath {
135        &self.inner.path
136    }
137}
rust_supervisor/role/context/service.rs

rust_supervisor/role/context/
service.rs
