open_net/api/subscription/
mod.rs1use crate::error::{ErrorKind, NetError};
4use crate::Result;
5use std::fmt;
6use std::sync::{Arc, Mutex, MutexGuard, Weak};
7use std::task::{Context, Poll};
8
9pub(crate) mod common_executor;
10mod dispatch;
11mod event;
12mod event_registration;
13pub use event::EventReceiver;
14pub(crate) use event::{
15 event_channel, EventOverflow, EventPublisher, EventQueueLimit, EventResources,
16};
17#[cfg(feature = "ws-client")]
18pub(crate) use event::{EventPublication, EventSeed};
19mod registration;
20mod source;
21pub(crate) use source::{StatePublication, StatePublisher, StateSource};
22
23pub(crate) trait CallbackExecutor: Send + Sync + 'static {
25 fn ensure_ready(&self) -> Result<()>;
26 fn submit(&self, job: Box<dyn FnOnce() + Send + 'static>) -> Result<()>;
27}
28trait SubscriptionControl: Send + Sync {
29 fn is_active(&self) -> bool;
30 fn unsubscribe(&self) -> bool;
31 fn poll_close(&self, cx: &mut Context<'_>) -> Poll<Result<()>>;
32}
33fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
34 match mutex.lock() {
35 Ok(guard) => guard,
36 Err(poisoned) => {
37 crate::log_e!(crate::common::log::log_def::LogType::Common;
38 "subscription_lock", "kind|reason", format!("{:?}", ErrorKind::Internal), "poisoned mutex recovered");
39 poisoned.into_inner()
40 }
41 }
42}
43
44#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
45pub struct SubscriptionId(u64);
51impl SubscriptionId {
52 pub fn as_u64(self) -> u64 {
57 self.0
58 }
59}
60impl fmt::Display for SubscriptionId {
61 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
62 self.0.fmt(formatter)
63 }
64}
65
66#[must_use]
67pub struct StateReceiver<T> {
74 registration: Arc<registration::Registration<T>>,
75 owns_subscription: bool,
76}
77impl<T> fmt::Debug for StateReceiver<T> {
78 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
79 formatter
80 .debug_struct("StateReceiver")
81 .field("id", &self.registration.id)
82 .finish_non_exhaustive()
83 }
84}
85impl<T: Clone> StateReceiver<T> {
86 #[cfg_attr(not(any(feature = "http-client", test)), allow(dead_code))]
89 pub(crate) fn bind_lifetime(&self, lifetime: impl Send + Sync + 'static) -> Result<()> {
90 self.registration.bind_lifetime(Box::new(lifetime))
91 }
92 pub fn id(&self) -> SubscriptionId {
94 self.registration.id
95 }
96 pub fn current(&self) -> T {
101 self.registration.current()
102 }
103 pub async fn recv(&mut self) -> Result<Option<T>> {
110 futures::future::poll_fn(|cx| self.registration.poll_next(cx))
111 .await
112 .transpose()
113 }
114 pub fn unsubscribe(&self) -> bool {
119 self.registration.unsubscribe()
120 }
121 pub fn into_callback<F>(mut self, callback: F) -> Result<Subscription>
128 where
129 T: Send + Sync + 'static,
130 F: Fn(CallbackContext, Result<T>) + Send + Sync + 'static,
131 {
132 self.registration.install_callback(callback)?;
133 self.owns_subscription = false;
134 Ok(Subscription {
135 id: self.registration.id,
136 control: self.registration.clone(),
137 })
138 }
139}
140impl<T: Clone> futures::Stream for StateReceiver<T> {
141 type Item = Result<T>;
142 fn poll_next(self: std::pin::Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
143 self.registration.poll_next(cx)
144 }
145}
146impl<T> Drop for StateReceiver<T> {
147 fn drop(&mut self) {
148 if self.owns_subscription {
149 self.registration.unsubscribe();
150 }
151 }
152}
153
154#[must_use]
155pub struct Subscription {
161 id: SubscriptionId,
162 control: Arc<dyn SubscriptionControl>,
163}
164impl Subscription {
165 pub fn id(&self) -> SubscriptionId {
167 self.id
168 }
169 pub fn is_active(&self) -> bool {
171 self.control.is_active()
172 }
173 pub fn unsubscribe(&self) -> bool {
178 self.control.unsubscribe()
179 }
180 pub async fn close(self) -> Result<()> {
187 self.unsubscribe();
188 futures::future::poll_fn(|cx| self.control.poll_close(cx)).await
189 }
190}
191impl Drop for Subscription {
192 fn drop(&mut self) {
193 self.control.unsubscribe();
194 }
195}
196impl fmt::Debug for Subscription {
197 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
198 formatter
199 .debug_struct("Subscription")
200 .field("id", &self.id)
201 .field("active", &self.is_active())
202 .finish()
203 }
204}
205
206#[derive(Clone)]
207pub struct CallbackContext {
213 id: SubscriptionId,
214 control: Weak<dyn SubscriptionControl>,
215}
216impl CallbackContext {
217 pub fn id(&self) -> SubscriptionId {
219 self.id
220 }
221 pub fn unsubscribe(&self) -> bool {
227 self.control
228 .upgrade()
229 .is_some_and(|control| control.unsubscribe())
230 }
231}
232impl fmt::Debug for CallbackContext {
233 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
234 formatter
235 .debug_struct("CallbackContext")
236 .field("id", &self.id)
237 .finish_non_exhaustive()
238 }
239}
240
241#[cfg(test)]
242mod lifetime_tests;
243#[cfg(test)]
244mod tests;
245
246#[cfg(test)]
247mod event_regression_tests;
248#[cfg(test)]
249mod event_tests;