open_net/api/log/logger.rs
1use super::{LogListener, LogType};
2use crate::common::log::logger::{self, SubscriptionState};
3use std::io;
4use std::sync::Arc;
5
6const DEFAULT_QUEUE_CAPACITY: usize = 256;
7
8/// Owns a single filtered log subscription. Dropping it stops accepting records,
9/// discards queued records and wakes an idle callback thread without waiting for
10/// an already-running callback. This handle may be shared or moved across threads.
11///
12/// Callbacks run sequentially on a dedicated thread. They may query the SDK,
13/// replace/unsubscribe listeners or panic without blocking network workers. Logs
14/// synchronously produced on the callback thread are suppressed to prevent loops.
15/// Work explicitly spawned by a callback must avoid creating its own log loop.
16#[must_use = "keep the subscription alive to continue receiving logs"]
17pub struct LogSubscription {
18 pub(crate) id: u64,
19 pub(crate) state: Arc<SubscriptionState>,
20}
21
22impl LogSubscription {
23 /// Total records discarded because this subscription's queue was full.
24 pub fn dropped_count(&self) -> u64 {
25 self.state.dropped_count()
26 }
27}
28
29impl Drop for LogSubscription {
30 fn drop(&mut self) {
31 logger::unregister(self.id, &self.state);
32 }
33}
34
35/// Callback-only logging. The library does not print or persist log records.
36pub struct OpenNetLogger;
37
38impl OpenNetLogger {
39 /// Registers an independent subscription with a queue of 256 records.
40 ///
41 /// Only explicitly listed origins are accepted, including for overflow reports.
42 /// An empty type list is invalid. The returned handle must remain alive.
43 /// Registration can fail if the callback thread cannot be created.
44 pub fn register_log_listener(
45 listener: LogListener,
46 log_types: &[LogType],
47 ) -> io::Result<LogSubscription> {
48 Self::register_log_listener_with_capacity(listener, log_types, DEFAULT_QUEUE_CAPACITY)
49 }
50
51 /// Registers a subscription with a bounded number of queued records.
52 ///
53 /// Producers never wait for queue capacity. Overflow increments
54 /// [`LogSubscription::dropped_count`] and is reported after the consumer resumes
55 /// as a synthetic `log_subscription_overflow-S` record using the first listed
56 /// origin. Zero capacity and an empty type list return `InvalidInput`.
57 pub fn register_log_listener_with_capacity(
58 listener: LogListener,
59 log_types: &[LogType],
60 capacity: usize,
61 ) -> io::Result<LogSubscription> {
62 logger::register_log_listener_with_capacity(listener, log_types, capacity)
63 }
64
65 /// Clears all global subscriptions without waiting for callbacks in progress.
66 pub fn clear_global_log_listener() {
67 logger::clear_global_log_listener();
68 }
69
70 /// Used by macros to avoid evaluating arguments for disabled origins.
71 #[doc(hidden)]
72 pub fn is_enabled(log_type: LogType) -> bool {
73 logger::is_enabled(log_type)
74 }
75}