Skip to main content

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 Logger;
37
38impl Logger {
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}