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}