Skip to main content

ntex_service/
bind.rs

1use crate::{ReadyCallback, ReadyLink, ReadyNotifier, Service, readiness::ReadyScope};
2
3/// Initialization-only access to a service's readiness dependencies.
4///
5/// A pipeline or [`crate::Ctx::create`] supplies this borrowed context to
6/// [`Service::bind`] before the new service's readiness checks, calls, or shutdown.
7/// Subscribe every notification source and bind every existing child used by
8/// the service, including call-only children.
9/// Dependencies must be available from the service itself. Binding cannot
10/// perform runtime operations.
11///
12/// The context cannot be constructed by services or retained for later use.
13/// Runtime [`crate::Ctx`] cannot register dependencies directly; its explicit
14/// [`create`](crate::Ctx::create) method initializes and binds new children.
15///
16/// ```
17/// use ntex_service::{BindCtx, Ctx, ReadyCallback, ReadyNotifier, Service};
18///
19/// struct Forward<S> {
20///     inner: S,
21///     changed: ReadyNotifier,
22///     on_notify: ReadyCallback,
23/// }
24///
25/// impl<S: Service<(), u8>> Service<(), u8> for Forward<S> {
26///     type Res = S::Res;
27///     type Error = S::Error;
28///
29///     fn bind(&self, ctx: BindCtx<'_>) {
30///         ctx.subscribe(&self.changed);
31///         ctx.on_notify(&self.on_notify);
32///         ctx.bind(&self.inner);
33///     }
34///
35///     async fn ready(&self, ctx: Ctx<'_, Self>) -> Result<(), Self::Error> {
36///         ctx.ready(&self.inner).await
37///     }
38///
39///     async fn call(&self, req: u8, ctx: Ctx<'_, Self>) -> Result<Self::Res, Self::Error> {
40///         ctx.call(&self.inner, req).await
41///     }
42/// }
43/// ```
44///
45/// ```compile_fail
46/// use ntex_service::{Ctx, ReadyNotifier};
47/// fn register_later(ctx: Ctx<'_, ()>, changed: &ReadyNotifier) {
48///     ctx.subscribe(changed);
49/// }
50/// ```
51///
52/// ```compile_fail
53/// use ntex_service::{BindCtx, Ctx, Service};
54/// fn bind_later<S: Service<(), ()>>(ctx: Ctx<'_, ()>, service: &S) {
55///     service.bind(ctx);
56/// }
57/// ```
58///
59/// ```compile_fail
60/// use ntex_service::{BindCtx, Ctx, Service};
61/// struct Retained(std::cell::RefCell<Option<BindCtx<'static>>>);
62/// impl Service<(), ()> for Retained {
63///     type Res = ();
64///     type Error = ();
65///     fn bind(&self, ctx: BindCtx<'_>) {
66///         *self.0.borrow_mut() = Some(ctx);
67///     }
68///     async fn call(&self, _: (), _: Ctx<'_, Self>) -> Result<(), ()> {
69///         Ok(())
70///     }
71/// }
72/// ```
73#[derive(Debug)]
74pub struct BindCtx<'a> {
75    scope: &'a ReadyScope,
76}
77
78impl<'a> BindCtx<'a> {
79    pub(crate) fn new(scope: &'a ReadyScope) -> Self {
80        Self { scope }
81    }
82
83    /// Subscribes this scope to a source of readiness changes.
84    ///
85    /// Subscriptions are appended without deduplication and persist across
86    /// completed or cancelled checks. Repeated subscriptions cause repeated
87    /// invalidations and callback delivery. Entries for dropped scopes are
88    /// ignored and remain stored until the source is dropped.
89    ///
90    /// # Panics
91    ///
92    /// Panics if the source is currently delivering a notification.
93    pub fn subscribe(&self, source: &ReadyNotifier) {
94        self.scope.subscribe(source);
95    }
96
97    /// Subscribes this scope to another pipeline's readiness invalidations.
98    ///
99    /// Obtain the endpoint with [`crate::Pipeline::readiness_link`]. Repeated
100    /// registration is idempotent and survives dropping the link handle.
101    /// This does not run a readiness check: the service must still await the
102    /// source pipeline's readiness. A dropped source makes the link inert.
103    pub fn subscribe_pipeline(&self, link: &ReadyLink) {
104        self.scope.subscribe_pipeline(link);
105    }
106
107    /// Registers a callback for notifications reaching this readiness scope.
108    ///
109    /// Raw services share this scope; a [`crate::ReadyBinding`] owns its own.
110    /// Repeated registration of the same handle is idempotent. See
111    /// [`ReadyCallback`] for notification and lifetime semantics.
112    /// The callback receives this scope's data from
113    /// [`crate::ReadyBinding::with_data`], or `0` by default.
114    ///
115    /// # Panics
116    ///
117    /// Panics if this scope is currently executing notification callbacks.
118    pub fn on_notify(&self, callback: &ReadyCallback) {
119        self.scope.on_notify(callback);
120    }
121
122    /// Binds a child service to this readiness scope.
123    ///
124    /// Raw services share this scope. A [`crate::ReadyBinding`] uses its own
125    /// scope and registers it as a dependency of this one.
126    /// Use explicit type arguments when the child has multiple [`Service`]
127    /// implementations.
128    /// For pipeline children, use [`crate::Pipeline::bind_to`] instead.
129    pub fn bind<S, St, Req>(&self, service: &S)
130    where
131        S: Service<St, Req>,
132    {
133        service.bind(Self::new(self.scope));
134    }
135
136    pub(crate) fn depend_on(&self, scope: &ReadyScope) {
137        self.scope.depend_on(scope);
138    }
139}