nice_plug_core/
debug.rs

1//! Macros for logging and debug assertions. [`nice_dbg!()`], [`nice_trace!()`], and the
2//! `nice_debug_assert_*!()` macros are compiled out during release builds, so they can be used for
3//! asserting adiditonal invariants in debug builds. Check the [`nice_log!()`] macro for more
4//! information on nice-plug's logger. None of the logging functions are realtime-safe, and you
5//! should avoid using them during release builds in any of the functions that may be called from an
6//! audio thread.
7
8// NOTE: Exporting macros in Rust is a bit weird. `#[macro_export]` causes them to be exported to
9//       the crate root, but that makes it difficult to include just the macros without using
10//       `#[macro_use] extern crate nice-plug;`. That's why the macros are also re-exported from this
11//       module.
12
13/// Write something to the logger. This defaults to STDERR unless the user is running Windows and a
14/// debugger has been attached, in which case `OutputDebugString()` will be used instead.
15///
16/// The logger's behavior can be controlled by setting the `NICE_LOG` environment variable to:
17///
18/// - `stderr`, in which case the log output always gets written to STDERR.
19/// - `windbg` (only on Windows), in which case the output always gets logged using
20///   `OutputDebugString()`.
21/// - A file path, in which case the output gets appended to the end of that file which will be
22///   created if necessary.
23#[macro_export]
24macro_rules! nice_log {
25    ($($args:tt)*) => (
26        $crate::log::info!($($args)*)
27    );
28}
29#[doc(inline)]
30pub use nice_log;
31
32/// Similar to `nice_log!()`, but less subtle. Used for printing warnings.
33#[macro_export]
34macro_rules! nice_warn {
35    ($($args:tt)*) => (
36        $crate::log::warn!($($args)*)
37    );
38}
39#[doc(inline)]
40pub use nice_warn;
41
42/// Similar to `nice_log!()`, but more scream-y. Used for printing fatal errors.
43#[macro_export]
44macro_rules! nice_error {
45    ($($args:tt)*) => (
46        $crate::log::error!($($args)*)
47    );
48}
49#[doc(inline)]
50pub use nice_error;
51
52/// The same as `nice_log!()`, but with source and thread information. Like the
53/// `nice_debug_assert*!()` macros, this is only shown when compiling in debug mode.
54#[macro_export]
55macro_rules! nice_trace {
56    ($($args:tt)*) => (
57        $crate::util::permit_alloc(|| $crate::log::trace!($($args)*))
58    );
59}
60#[doc(inline)]
61pub use nice_trace;
62
63/// Analogues to the `dbg!()` macro, but respecting the `NICE_LOG` environment variable and with all
64/// of the same logging features as the other `nice_*!()` macros. Like the `nice_debug_assert*!()`
65/// macros, this is only shown when compiling in debug mode, but the macro will still return the
66/// value in non-debug modes.
67#[macro_export]
68macro_rules! nice_dbg {
69    () => {
70        $crate::util::permit_alloc(|| $crate::log::debug!(""));
71    };
72    ($val:expr $(,)?) => {
73        // Match here acts as a let-binding: https://stackoverflow.com/questions/48732263/why-is-rusts-assert-eq-implemented-using-a-match/48732525#48732525
74        match $val {
75            tmp => {
76                $crate::util::permit_alloc(|| $crate::log::debug!("{} = {:#?}", stringify!($val), &tmp));
77                tmp
78            }
79        }
80    };
81    ($($val:expr),+ $(,)?) => { ($($crate::nice_dbg!($val)),+,) };
82}
83#[doc(inline)]
84pub use nice_dbg;
85
86/// A `debug_assert!()` analogue that prints the error with line number information instead of
87/// panicking. During tests this is upgraded to a regular panicking `debug_assert!()`.
88///
89/// TODO: Detect if we're running under a debugger, and trigger a break if we are
90#[macro_export]
91macro_rules! nice_debug_assert {
92    ($cond:expr $(,)?) => (
93        #[allow(clippy::neg_cmp_op_on_partial_ord)]
94        if cfg!(test) {
95           debug_assert!($cond);
96        } else if cfg!(debug_assertions) && !$cond {
97            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($cond))));
98        }
99    );
100    ($cond:expr, $format:expr $(, $($args:tt)*)?) => (
101        #[allow(clippy::neg_cmp_op_on_partial_ord)]
102        if cfg!(test) {
103           debug_assert!($cond, $format, $($($args)*)?);
104        } else if cfg!(debug_assertions) && !$cond {
105            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($cond), ", ", $format), $($($args)*)?));
106        }
107    );
108}
109#[doc(inline)]
110pub use nice_debug_assert;
111
112/// An unconditional debug assertion failure, for if the condition has already been checked
113/// elsewhere. See [`nice_debug_assert!()`] for more information.
114#[macro_export]
115macro_rules! nice_debug_assert_failure {
116    () => (
117        if cfg!(test) {
118           debug_assert!(false, "Debug assertion failed");
119        } else if cfg!(debug_assertions) {
120            $crate::util::permit_alloc(|| $crate::log::warn!("Debug assertion failed"));
121        }
122    );
123    ($format:expr $(, $($args:tt)*)?) => (
124        if cfg!(test) {
125           debug_assert!(false, concat!("Debug assertion failed: ", $format), $($($args)*)?);
126        } else if cfg!(debug_assertions) {
127            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", $format), $($($args)*)?));
128        }
129    );
130}
131#[doc(inline)]
132pub use nice_debug_assert_failure;
133
134/// A `debug_assert_eq!()` analogue that prints the error with line number information instead of
135/// panicking. See [`nice_debug_assert!()`] for more information.
136#[macro_export]
137macro_rules! nice_debug_assert_eq {
138    ($left:expr, $right:expr $(,)?) => (
139        #[allow(clippy::neg_cmp_op_on_partial_ord)]
140        if cfg!(test) {
141           debug_assert_eq!($left, $right);
142        } else if cfg!(debug_assertions) && $left != $right {
143            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($left), " != ", stringify!($right))));
144        }
145    );
146    ($left:expr, $right:expr, $format:expr $(, $($args:tt)*)?) => (
147        #[allow(clippy::neg_cmp_op_on_partial_ord)]
148        if cfg!(test) {
149           debug_assert_eq!($left, $right, $format, $($($args)*)?);
150        } else if cfg!(debug_assertions) && $left != $right {
151            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($left), " != ", stringify!($right), ", ", $format), $($($args)*)?));
152        }
153    );
154}
155#[doc(inline)]
156pub use nice_debug_assert_eq;
157
158/// A `debug_assert_ne!()` analogue that prints the error with line number information instead of
159/// panicking. See [`nice_debug_assert!()`] for more information.
160#[macro_export]
161macro_rules! nice_debug_assert_ne {
162    ($left:expr, $right:expr $(,)?) => (
163        #[allow(clippy::neg_cmp_op_on_partial_ord)]
164        if cfg!(test) {
165           debug_assert_ne!($left, $right);
166        } else if cfg!(debug_assertions) && $left == $right {
167            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($left), " == ", stringify!($right))));
168        }
169    );
170    ($left:expr, $right:expr, $format:expr $(, $($args:tt)*)?) => (
171        #[allow(clippy::neg_cmp_op_on_partial_ord)]
172        if cfg!(test) {
173           debug_assert_ne!($left, $right, $format, $($($args)*)?);
174        } else if cfg!(debug_assertions) && $left == $right  {
175            $crate::util::permit_alloc(|| $crate::log::warn!(concat!("Debug assertion failed: ", stringify!($left), " == ", stringify!($right), ", ", $format), $($($args)*)?));
176        }
177    );
178}
179#[doc(inline)]
180pub use nice_debug_assert_ne;
nice_plug_core/debug.rs

nice_plug_core/
debug.rs
