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 pruned as later subscriptions grow the source; see
89 /// [`ReadyNotifier`].
90 ///
91 /// # Panics
92 ///
93 /// Panics if the source is currently delivering a notification.
94 pub fn subscribe(&self, source: &ReadyNotifier) {
95 self.scope.subscribe(source);
96 }
97
98 /// Subscribes this scope to another pipeline's readiness invalidations.
99 ///
100 /// Obtain the endpoint with [`crate::Pipeline::readiness_link`]. Repeated
101 /// registration is idempotent and survives dropping the link handle.
102 /// This does not run a readiness check: the service must still await the
103 /// source pipeline's readiness. A dropped source makes the link inert.
104 pub fn subscribe_pipeline(&self, link: &ReadyLink) {
105 self.scope.subscribe_pipeline(link);
106 }
107
108 /// Registers a callback for notifications reaching this readiness scope.
109 ///
110 /// Raw services share this scope; a [`crate::ReadyBinding`] owns its own.
111 /// Repeated registration of the same handle is idempotent. See
112 /// [`ReadyCallback`] for notification and lifetime semantics.
113 /// The callback receives this scope's data from
114 /// [`crate::ReadyBinding::with_data`], or `0` by default.
115 ///
116 /// # Panics
117 ///
118 /// Panics if this scope is currently executing notification callbacks.
119 pub fn on_notify(&self, callback: &ReadyCallback) {
120 self.scope.on_notify(callback);
121 }
122
123 /// Binds a child service to this readiness scope.
124 ///
125 /// Raw services share this scope. A [`crate::ReadyBinding`] uses its own
126 /// scope and registers it as a dependency of this one.
127 /// Use explicit type arguments when the child has multiple [`Service`]
128 /// implementations.
129 /// For pipeline children, use [`crate::Pipeline::bind_to`] instead.
130 pub fn bind<S, St, Req>(&self, service: &S)
131 where
132 S: Service<St, Req>,
133 {
134 service.bind(Self::new(self.scope));
135 }
136
137 pub(crate) fn depend_on(&self, scope: &ReadyScope) {
138 self.scope.depend_on(scope);
139 }
140}