A macro for defining #[cfg] if-else statements.
The macro provided by this crate, cfg_if, is similar to the if/elif C
+preprocessor macro by allowing definition of a cascade of #[cfg] cases,
+emitting the implementation which matches first.
This allows you to conveniently provide a long list #[cfg]'d blocks of code
+without having to rewrite each clause multiple times.
+cfg_if::cfg_if! { + if #[cfg(unix)] { + fn foo() { /* unix specific functionality */ } + } else if #[cfg(target_pointer_width = "32")] { + fn foo() { /* non-unix, 32-bit functionality */ } + } else { + fn foo() { /* fallback implementation */ } + } +} +
| cfg_if | The main macro provided by this crate. See crate documentation for more +information. + |
Redirecting to macro.cfg_if.html...
+ + + \ No newline at end of file diff --git a/cfg_if/macro.cfg_if.html b/cfg_if/macro.cfg_if.html new file mode 100644 index 0000000..cbde7d5 --- /dev/null +++ b/cfg_if/macro.cfg_if.html @@ -0,0 +1,23 @@ +The main macro provided by this crate. See crate documentation for more +information.
+An enum representing the available verbosity levels of the logger.
+Typical usage includes: checking if a certain Level is enabled with
+log_enabled!, specifying the Level of
+log!, and comparing a Level directly to a
+LevelFilter.
The "error" level.
+Designates very serious errors.
+The "warn" level.
+Designates hazardous situations.
+The "info" level.
+Designates useful information.
+The "debug" level.
+Designates lower priority information.
+The "trace" level.
+Designates very low priority, often extremely verbose, information.
+impl Level[src]pub fn max() -> Level[src]Returns the most verbose logging level.
+pub fn to_level_filter(&self) -> LevelFilter[src]Converts the Level to the equivalent LevelFilter.
pub fn as_str(&self) -> &'static str[src]Returns the string representation of the Level.
This returns the same string as the fmt::Display implementation.
impl Clone for Level[src]pub fn clone(&self) -> Level[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl Copy for Level[src]impl Debug for Level[src]impl Display for Level[src]impl Eq for Level[src]impl FromStr for Level[src]type Err = ParseLevelErrorThe associated error which can be returned from parsing.
+pub fn from_str(level: &str) -> Result<Level, <Level as FromStr>::Err>[src]impl Hash for Level[src]pub fn hash<__H>(&self, state: &mut __H) where
__H: Hasher, [src]pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher, 1.3.0[src]impl Ord for Level[src]pub fn cmp(&self, other: &Level) -> Ordering[src]#[must_use]pub fn max(self, other: Self) -> Self1.21.0[src]#[must_use]pub fn min(self, other: Self) -> Self1.21.0[src]#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self1.50.0[src]impl PartialEq<Level> for LevelFilter[src]pub fn eq(&self, other: &Level) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialEq<Level> for Level[src]pub fn eq(&self, other: &Level) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialEq<LevelFilter> for Level[src]pub fn eq(&self, other: &LevelFilter) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialOrd<Level> for LevelFilter[src]pub fn partial_cmp(&self, other: &Level) -> Option<Ordering>[src]pub fn lt(&self, other: &Level) -> bool[src]pub fn le(&self, other: &Level) -> bool[src]pub fn gt(&self, other: &Level) -> bool[src]pub fn ge(&self, other: &Level) -> bool[src]impl PartialOrd<Level> for Level[src]pub fn partial_cmp(&self, other: &Level) -> Option<Ordering>[src]pub fn lt(&self, other: &Level) -> bool[src]pub fn le(&self, other: &Level) -> bool[src]pub fn gt(&self, other: &Level) -> bool[src]pub fn ge(&self, other: &Level) -> bool[src]impl PartialOrd<LevelFilter> for Level[src]pub fn partial_cmp(&self, other: &LevelFilter) -> Option<Ordering>[src]pub fn lt(&self, other: &LevelFilter) -> bool[src]pub fn le(&self, other: &LevelFilter) -> bool[src]pub fn gt(&self, other: &LevelFilter) -> bool[src]pub fn ge(&self, other: &LevelFilter) -> bool[src]impl StructuralEq for Level[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]An enum representing the available verbosity level filters of the logger.
+A LevelFilter may be compared directly to a Level. Use this type
+to get and set the maximum log level with max_level() and set_max_level.
A level lower than all log levels.
+Corresponds to the Error log level.
Corresponds to the Warn log level.
Corresponds to the Info log level.
Corresponds to the Debug log level.
Corresponds to the Trace log level.
impl LevelFilter[src]pub fn max() -> LevelFilter[src]Returns the most verbose logging level filter.
+pub fn to_level(&self) -> Option<Level>[src]Converts self to the equivalent Level.
Returns None if self is LevelFilter::Off.
pub fn as_str(&self) -> &'static str[src]Returns the string representation of the LevelFilter.
This returns the same string as the fmt::Display implementation.
impl Clone for LevelFilter[src]pub fn clone(&self) -> LevelFilter[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl Copy for LevelFilter[src]impl Debug for LevelFilter[src]impl Display for LevelFilter[src]impl Eq for LevelFilter[src]impl FromStr for LevelFilter[src]type Err = ParseLevelErrorThe associated error which can be returned from parsing.
+pub fn from_str(
level: &str
) -> Result<LevelFilter, <LevelFilter as FromStr>::Err>[src]impl Hash for LevelFilter[src]pub fn hash<__H>(&self, state: &mut __H) where
__H: Hasher, [src]pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher, 1.3.0[src]impl Ord for LevelFilter[src]pub fn cmp(&self, other: &LevelFilter) -> Ordering[src]#[must_use]pub fn max(self, other: Self) -> Self1.21.0[src]#[must_use]pub fn min(self, other: Self) -> Self1.21.0[src]#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self1.50.0[src]impl PartialEq<Level> for LevelFilter[src]pub fn eq(&self, other: &Level) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialEq<LevelFilter> for LevelFilter[src]pub fn eq(&self, other: &LevelFilter) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialEq<LevelFilter> for Level[src]pub fn eq(&self, other: &LevelFilter) -> bool[src]#[must_use]pub fn ne(&self, other: &Rhs) -> bool1.0.0[src]impl PartialOrd<Level> for LevelFilter[src]pub fn partial_cmp(&self, other: &Level) -> Option<Ordering>[src]pub fn lt(&self, other: &Level) -> bool[src]pub fn le(&self, other: &Level) -> bool[src]pub fn gt(&self, other: &Level) -> bool[src]pub fn ge(&self, other: &Level) -> bool[src]impl PartialOrd<LevelFilter> for Level[src]pub fn partial_cmp(&self, other: &LevelFilter) -> Option<Ordering>[src]pub fn lt(&self, other: &LevelFilter) -> bool[src]pub fn le(&self, other: &LevelFilter) -> bool[src]pub fn gt(&self, other: &LevelFilter) -> bool[src]pub fn ge(&self, other: &LevelFilter) -> bool[src]impl PartialOrd<LevelFilter> for LevelFilter[src]pub fn partial_cmp(&self, other: &LevelFilter) -> Option<Ordering>[src]pub fn lt(&self, other: &LevelFilter) -> bool[src]pub fn le(&self, other: &LevelFilter) -> bool[src]pub fn gt(&self, other: &LevelFilter) -> bool[src]pub fn ge(&self, other: &LevelFilter) -> bool[src]impl StructuralEq for LevelFilter[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]pub unsafe fn dequeue(delogger: impl Delogger, buf: &mut [u8]) -> &str
The core "read from circular buffer" method. Marked unsafe to discourage use!
+Unfortunately exposed for all to see, as the delog! macro needs access to it to
+implement the logger at call site. Hence marked as unsafe.
pub unsafe fn enqueue(delogger: impl Delogger, record: &Record<'_>)
The core "write to circular buffer" method. Marked unsafe to discourage use!
+Unfortunately exposed for all to see, as the delog! macro needs access to it to
+implement the logger at call site. Hence marked as unsafe.
pub fn logger() -> &'static mut Option<&'static dyn TryLogWithStatistics>
Returns a reference to the logger (as TryLogWithStatistics implementation)
pub unsafe fn try_enqueue(
delogger: impl Delogger,
record: &Record<'_>
) -> Result<(), ()>
The fallible "write to circular buffer" method. Marked unsafe to discourage use!
+Unfortunately exposed for all to see, as the delog! macro needs access to it to
+implement the logger at call site. Hence marked as unsafe.
This implementation needs some HEAVY testing. It is unsound on PC, where the OS +can schedule threads in any manner, but assumed to be sound in ARM Cortex-M NVIC +situations, where interrupts are "nested", in the sense that one may be interrupted, +then the interrupter can, ..., then the interrupter hands back control, ..., and finally +the original caller of this function regains control.
+In this situation, we keep track of three counters (read, written, claimed), with
+invariants read <= written <= claimed. Each writer pessimistically gauges sufficient
+capacity for its log by checking claimed + size <= read + capacity, accounting for the
+wraparound. If so, the writer atomically advances the claim counter, and starts copying
+its data in this newly claimed space. At the end, it is the duty of the "first" caller
+to advance the written counter to the correct state.
pub fn HexStr<T: ?Sized, U: Unsigned, S: Separator>(
value: &T
) -> HexStr<'_, T, U, S>
Explicitly construct a newtype to format with.
+The first generic parameter specifies the block size in bytes, the second parameter +the separator string.
+This function is just here for documentation of what the hex_str! macro
+does internally (using the undocumented typeint! and typesep! macros).
+use delog::hex::{HexStr, Separator, Unsigned}; + +// typeint!(U3, 3); +struct U3 {} +impl Unsigned for U3 { + const N: usize = 3; +} + +// typesep!(Pipe, "|"); +struct Pipe {} +impl Separator for Pipe { + const SEPARATOR: &'static str = "|"; +} + +let four_bytes = &[7u8, 0xA1, 255, 0xC7]; +let hex_str = HexStr::<_, U3, Pipe>(four_bytes); + +assert_eq!(format!("{}", hex_str), "07A1FF|C7");
Convenient Display and other traits for binary data.
Standard Rust uses the fmt::UpperHex and LowerHex traits to implement hexadecimal
+representations for use in format strings. For instance,
+format_args!("{:02X?}", &[7, 0xA1, 0xFF]) produces the string "[07, A1, FF]".
+assert_eq!(format!("{:02X?}", [7u8, 0xA1, 0xFF].as_ref()), "[07, A1, FF]");
However, this only works for the Debug trait, not Display; needs extra dancing
+to pad with leading zeros, and is not very compact when debugging binary data formats.
The idea of this module is to generate newtypes around byte arrays/slices, and implement the fmt traits on these.
+In release builds, this is all compiled out and translates to direct instructions for the formatting machinery.
The ide to implement truncated outputs comes from the hex_fmt library, which we refer to
+for additional newtypes that can be used.
+use delog::{hex_str, hexstr}; + +let data = &[7u8, 0xA1, 255, 0xC7]; + +assert_eq!(format!("{}", hexstr!(data)), "07A1FFC7"); +assert_eq!(format!("{:x}", hexstr!(data)), "07a1ffc7"); +assert_eq!(format!("{:2x}", hex_str!(data)), "07..c7"); +assert_eq!(format!("{:<3x}", hex_str!(data)), "07 a1 ff.."); +assert_eq!(format!("{:>3x}", hex_str!(data)), "..a1 ff c7"); +assert_eq!(format!("{}", hex_str!(data, 2)), "07A1 FFC7"); +assert_eq!(format!("{:<3}", hex_str!(data, sep: "|")), "07|A1|FF..");
| HexStr | Zero-sized wrapper newtype, allowing grouping bytes in blocks of N hexadecimals +during formatting. + |
| U1 | A type that represents the integer |
| Separator | A type that specifies a separator str. + |
| Unsigned | A type that specifies an unsigned integer. + |
| HexStr | Explicitly construct a newtype to format with. + |
Zero-sized wrapper newtype, allowing grouping bytes in blocks of N hexadecimals +during formatting.
+Use the method with the same name to construct this from your byte array or slice,
+or preferrably the hex_str! or hexstr! macro.
value: &'a TThe value to be formatted.
+impl<T: ?Sized, S, U> Debug for HexStr<'_, T, U, S> where
T: AsRef<[u8]>,
U: Unsigned,
S: Separator, [src]impl<T: ?Sized, U, S> Display for HexStr<'_, T, U, S> where
T: AsRef<[u8]>,
U: Unsigned,
S: Separator, [src]impl<'a, T: ?Sized, U, S> LowerHex for HexStr<'a, T, U, S> where
T: AsRef<[u8]>,
U: Unsigned,
S: Separator, [src]impl<'a, T: ?Sized, U, S> UpperHex for HexStr<'a, T, U, S> where
T: AsRef<[u8]>,
U: Unsigned,
S: Separator, [src]impl<'a, T: ?Sized, U, S> Send for HexStr<'a, T, U, S> where
S: Send,
T: Sync,
U: Send, [src]impl<'a, T: ?Sized, U, S> Sync for HexStr<'a, T, U, S> where
S: Sync,
T: Sync,
U: Sync, [src]impl<'a, T: ?Sized, U, S> Unpin for HexStr<'a, T, U, S> where
S: Unpin,
U: Unpin, [src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]A type that represents the integer 1.
impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]A type that specifies a separator str.
+A type that specifies an unsigned integer.
+We use this instead of typenum as the latter currently lacks
+a mapping from usize to the associated type.
printf()-debugging aka tracing)This is an implementation of the log::Log trait, suitable for use
+in both embedded and desktop environments.
It has two main goals:
+Moreover, setting the kill switch feature flag knock-it-off, any and all traces of logging
+are removed from the final binary.
++"Global settings subtractive (default all), local settings additive (default none) but with kill-switch."
+
From log, we inherit:
LevelFilter::Trace (i.e., everything), set via delog or
+log feature flags (multiple settings result in the most restrictive filter)Delogger trait. This can be changed by calls to
+the global set_max_level function in log.Libraries that use the logging macros from log are governed by the more restrictive of these two settings.
On the other hand, a library that uses the delog::generate_macros!() macro gains macros info!, warn!, etc.,
+which, by default, do nothing, and are completely optimized out.
If such a libray itself defines a feature log-all that is active, then logging calls with these macros are passed through
+and goverend by the global filters. Such a library can also define a feature such as
+log-info, which activates exactly the info-level logs; it is up to the library to define
+logic such as "log-info implies log-warn". There is a kill-switch: if the library defines a
+feature log-none, and some intermediate library activates one of the additive log-*
+features, setting log-none completely turns off logging for this library.
Compared to existing approaches such as ufmt, cortex-m-funnel and defmt,
+we pursue different values and requirements, namely:
core::fmt traits and the standard log library API.
+This means that, while libraries may "upgrade" their logging capabilities by using delog
+as drop-in replacement for their logging calls (see below), any existing library that already
+uses log is compatible. This, for our use cases, is a huge win, as opposed to using up "weirdness
+budget" and requiring custom tooling for something that is often trivial, throw-away, simple logging.trace!("{:?}", &suspicious_object) call at any time for
+any object that has a (possibly automatically derived) Debug trait implementation – without
+passing around structures and keeping on top of lifetimes.info! etc.
+are not directly sent to their final output, but instead are stored in a circular buffer
+that is "drained" by calling flush on the logger at a convenient moment, for instance
+in an idle loop.target argument to info! and friends
+with "!" as parameter, or using the additional immediate_info! and friends macros.log-based libraries, by adding the requisite features in Cargo.toml and
+replacing log with delog (see gate-tests for examples of this).fmt::UpperHex etc. implementations.Non-goals:
+core::fmt-ing facilities are not as
+efficient as one might hope, in our use cases we have sufficient flash and RAM to use these (and
+some hope that, someday, eventually, maybe, the formatting machinery will be revisited and
+improved at the root level, namely the language itself.)That said, we believe there is opportunity to extend delog in the defmt direction by
+using, e.g., the fmt::Binary trait, newtypes and sentinel values to embed raw binary
+representations of data in time-critical situations without formatting, deferring
+the extraction and actual formatting to some host-side mechanism.
The flushers and semihosting features mostly exist to share code within the examples,
+including the example feature. Without them, dependencies are quite minimal, and compilation fast.
The fallible and immediate features (default on) activate the try_*! and *_now! macros, respectively.
The current circular buffer implementation (v0.1.0) is definitely unsound on desktop.
+For embedded use, atomics are required (so no Cortex-M0/M1, and no plans to support non-atomic
+platforms, which are likely to also be too resource-constrained to support the bloat inherent
+in core::fmt). While we think the implemented circular buffer algorithm works for the "nested interrupt"
+setup of NVICs, it has not been tested much.
+The hope is that the worst case scenario is some slightly messed up log outputs.
We plan to iterate towards a v0.2.0 soon, making use of a separate "flusher" for the +"immediate" logging path. For instance, when logging via serial-over-USB, one might want immediate +logs to pend a separate RTIC interrupt handler that blocks until the logs are pushed and read +(allowing one to debug the boot process of a firmware), or one might want to just write to RTT +(or even semihosting xD) for these, during development.
+pub use log; |
| hex | Convenient |
| render | The default, minimal renderer, and some helper functions. + |
| delog | Generate a deferred logger with specified capacity and flushing mechanism. + |
| generate_macros | Generate logging macros that can be gated by library. + |
| hex_str | Compactly format byte arrays and slices as hexadecimals. + |
| hexstr | More compactly format byte arrays and slices as hexadecimals. + |
| try_log | Fallible (ungated) version of |
| Record | The "payload" of a log message. + |
| Statistics | Statistics on logger usage. + |
| Level | An enum representing the available verbosity levels of the logger. + |
| LevelFilter | An enum representing the available verbosity level filters of the logger. + |
| Delogger | Semi-abstract characterization of the deferred loggers that the |
| Flusher | A way to pass on logs, user supplied. + |
| Renderer | A way to format logs, user supplied. + |
| State | Trait for either state or statistics of loggers. + |
| TryLog | Fallible, panic-free version of the |
| TryLogWithStatistics | TryLog with some usage statistics on top. + |
| dequeue⚠ | The core "read from circular buffer" method. Marked unsafe to discourage use! + |
| enqueue⚠ | The core "write to circular buffer" method. Marked unsafe to discourage use! + |
| logger | Returns a reference to the logger (as |
| try_enqueue⚠ | The fallible "write to circular buffer" method. Marked unsafe to discourage use! + |
Redirecting to ../../delog/fn.dequeue.html...
+ + + \ No newline at end of file diff --git a/delog/logger/fn.enqueue.html b/delog/logger/fn.enqueue.html new file mode 100644 index 0000000..94efb01 --- /dev/null +++ b/delog/logger/fn.enqueue.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/fn.enqueue.html...
+ + + \ No newline at end of file diff --git a/delog/logger/fn.try_enqueue.html b/delog/logger/fn.try_enqueue.html new file mode 100644 index 0000000..9ded565 --- /dev/null +++ b/delog/logger/fn.try_enqueue.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/fn.try_enqueue.html...
+ + + \ No newline at end of file diff --git a/delog/logger/struct.Statistics.html b/delog/logger/struct.Statistics.html new file mode 100644 index 0000000..b15c109 --- /dev/null +++ b/delog/logger/struct.Statistics.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/struct.Statistics.html...
+ + + \ No newline at end of file diff --git a/delog/logger/trait.Delogger.html b/delog/logger/trait.Delogger.html new file mode 100644 index 0000000..370c5fe --- /dev/null +++ b/delog/logger/trait.Delogger.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/trait.Delogger.html...
+ + + \ No newline at end of file diff --git a/delog/logger/trait.State.html b/delog/logger/trait.State.html new file mode 100644 index 0000000..22e7f20 --- /dev/null +++ b/delog/logger/trait.State.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/trait.State.html...
+ + + \ No newline at end of file diff --git a/delog/logger/trait.TryLog.html b/delog/logger/trait.TryLog.html new file mode 100644 index 0000000..766a5e4 --- /dev/null +++ b/delog/logger/trait.TryLog.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/trait.TryLog.html...
+ + + \ No newline at end of file diff --git a/delog/logger/trait.TryLogWithStatistics.html b/delog/logger/trait.TryLogWithStatistics.html new file mode 100644 index 0000000..76ba1fb --- /dev/null +++ b/delog/logger/trait.TryLogWithStatistics.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to ../../delog/trait.TryLogWithStatistics.html...
+ + + \ No newline at end of file diff --git a/delog/macro.delog!.html b/delog/macro.delog!.html new file mode 100644 index 0000000..c17c02b --- /dev/null +++ b/delog/macro.delog!.html @@ -0,0 +1,10 @@ + + + + + + +Redirecting to macro.delog.html...
+ + + \ No newline at end of file diff --git a/delog/macro.delog.html b/delog/macro.delog.html new file mode 100644 index 0000000..e131851 --- /dev/null +++ b/delog/macro.delog.html @@ -0,0 +1,14 @@ +Generate a deferred logger with specified capacity and flushing mechanism.
+Note that only the final "runner" generates, initializes and flushes such a deferred logger.
+Libraries simply make calls to log::log!, or its drop-in replacement delog::log!,
+and/or its extension delog::log_now!, and/or its alternatives delog::try_log! and delog::try_log_now,
+and/or the local logging variants local_log!.
Redirecting to macro.generate_macros.html...
+ + + \ No newline at end of file diff --git a/delog/macro.generate_macros.html b/delog/macro.generate_macros.html new file mode 100644 index 0000000..30bfa97 --- /dev/null +++ b/delog/macro.generate_macros.html @@ -0,0 +1,13 @@ +Generate logging macros that can be gated by library.
+Realize that these macros are generated in the namespace of the consuming library, the one
+that actally later makes calls to local_warn! etc.
To see this in action, compile documentation using cargo doc --features example, or inspect
+the gate-tests/ subdirectory.
Redirecting to macro.hex_str.html...
+ + + \ No newline at end of file diff --git a/delog/macro.hex_str.html b/delog/macro.hex_str.html new file mode 100644 index 0000000..6f2f676 --- /dev/null +++ b/delog/macro.hex_str.html @@ -0,0 +1,21 @@ +Compactly format byte arrays and slices as hexadecimals.
+The second parameter refers to the number of bytes in a block (separated by spaces).
+ ++use delog::hex_str; +let four_bytes = &[7u8, 0xA1, 255, 0xC7]; +assert_eq!(format!("{:x}", hex_str!(four_bytes)), "07 a1 ff c7"); +assert_eq!(format!("{}", hex_str!(four_bytes, 2)), "07A1 FFC7"); +assert_eq!(format!("{}", hex_str!(four_bytes, 2, sep: "|")), "07A1|FFC7"); +assert_eq!(format!("{}", hex_str!(four_bytes, 3)), "07A1FF C7");
Redirecting to macro.hexstr.html...
+ + + \ No newline at end of file diff --git a/delog/macro.hexstr.html b/delog/macro.hexstr.html new file mode 100644 index 0000000..77d8585 --- /dev/null +++ b/delog/macro.hexstr.html @@ -0,0 +1,15 @@ +More compactly format byte arrays and slices as hexadecimals.
+ ++use delog::hexstr; +let four_bytes = &[7u8, 0xA1, 255, 0xC7]; +assert_eq!(format!("{}", hexstr!(four_bytes)), "07A1FFC7"); +assert_eq!(format!("{:x}", hexstr!(four_bytes)), "07a1ffc7");
Redirecting to macro.try_log.html...
+ + + \ No newline at end of file diff --git a/delog/macro.try_log.html b/delog/macro.try_log.html new file mode 100644 index 0000000..6b911df --- /dev/null +++ b/delog/macro.try_log.html @@ -0,0 +1,11 @@ +Fallible (ungated) version of log!.
pub fn default() -> &'static DefaultRenderer
The default, minimal renderer.
+pub fn render_arguments<'a>(buf: &'a mut [u8], args: Arguments<'_>) -> &'a [u8]
For some reason, there seems to be no existing method to easily render +fmt::Arguments in a pre-allocated byte array.
+That is what this does.
+pub fn render_record<'a>(buf: &'a mut [u8], record: &Record<'_>) -> &'a [u8]
Render record, based on feature flags.
+The default, minimal renderer, and some helper functions.
+| DefaultRenderer | Renders just the |
| RipgrepRenderer | Renders the |
| default | The default, minimal renderer. + |
| render_arguments | For some reason, there seems to be no existing method to easily render +fmt::Arguments in a pre-allocated byte array. + |
| render_record | Render record, based on feature flags. + |
Renders just the record.args().
impl Clone for DefaultRenderer[src]fn clone(&self) -> DefaultRenderer[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl Copy for DefaultRenderer[src]impl Renderer for DefaultRenderer[src]impl Send for DefaultRenderer[src]impl Sync for DefaultRenderer[src]impl Unpin for DefaultRenderer[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]Renders the record.args(), prefixed by level, target, and file, line if they are some.
impl Clone for RipgrepRenderer[src]fn clone(&self) -> RipgrepRenderer[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl Copy for RipgrepRenderer[src]impl Renderer for RipgrepRenderer[src]impl Send for RipgrepRenderer[src]impl Sync for RipgrepRenderer[src]impl Unpin for RipgrepRenderer[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]The "payload" of a log message.
+Record structures are passed as parameters to the log
+method of the Log trait. Logger implementors manipulate these
+structures in order to display log messages. Records are automatically
+created by the log! macro and so are not seen by log users.
Note that the level() and target() accessors are equivalent to
+self.metadata().level() and self.metadata().target() respectively.
+These methods are provided as a convenience for users of this structure.
The following example shows a simple logger that displays the level,
+module path, and message of any Record that is passed to it.
+struct SimpleLogger; + +impl log::Log for SimpleLogger { + fn enabled(&self, metadata: &log::Metadata) -> bool { + true + } + + fn log(&self, record: &log::Record) { + if !self.enabled(record.metadata()) { + return; + } + + println!("{}:{} -- {}", + record.level(), + record.target(), + record.args()); + } + fn flush(&self) {} +}
impl<'a> Record<'a>[src]pub fn builder() -> RecordBuilder<'a>[src]Returns a new builder.
+pub fn args(&self) -> &Arguments<'a>[src]The message body.
+pub fn metadata(&self) -> &Metadata<'a>[src]Metadata about the log directive.
+pub fn level(&self) -> Level[src]The verbosity level of the message.
+pub fn target(&self) -> &'a str[src]The name of the target of the directive.
+pub fn module_path(&self) -> Option<&'a str>[src]The module path of the message.
+pub fn module_path_static(&self) -> Option<&'static str>[src]The module path of the message, if it is a 'static string.
pub fn file(&self) -> Option<&'a str>[src]The source file containing the message.
+pub fn file_static(&self) -> Option<&'static str>[src]The module path of the message, if it is a 'static string.
pub fn line(&self) -> Option<u32>[src]The line containing the message.
+impl<'a> Clone for Record<'a>[src]pub fn clone(&self) -> Record<'a>[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl<'a> Debug for Record<'a>[src]impl<'a> !Send for Record<'a>[src]impl<'a> !Sync for Record<'a>[src]impl<'a> Unpin for Record<'a>[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]Statistics on logger usage.
+attempts: usizeHow often was one of the logging macros called.
+successes: usizeHow often was one of the logging macros called without early exit (e.g., buffer not full)
+flushes: usizeHow often was the flusher called.
+read: usizeHow many bytes were flushed so far.
+written: usizeHow many bytes were logged so far.
+impl Clone for Statistics[src]fn clone(&self) -> Statistics[src]pub fn clone_from(&mut self, source: &Self)1.0.0[src]impl Copy for Statistics[src]impl Debug for Statistics[src]impl<T> Any for T where
T: 'static + ?Sized, [src]impl<T> Borrow<T> for T where
T: ?Sized, [src]impl<T> BorrowMut<T> for T where
T: ?Sized, [src]pub fn borrow_mut(&mut self) -> &mut T[src]impl<T> From<T> for T[src]impl<T, U> Into<U> for T where
U: From<T>, [src]impl<T, U> TryFrom<U> for T where
U: Into<T>, [src]type Error = InfallibleThe type returned in the event of a conversion error.
+pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]impl<T, U> TryInto<U> for T where
U: TryFrom<T>, [src]Semi-abstract characterization of the deferred loggers that the delog! macro produces.
This trait is markes "unsafe" to signal that users should never (need to) "write their own",
+but always go through the delog! macro.
The user has access to the global logger via delog::logger(), but only as TryLog/Log
+implementation, not with this direct access to implementation details.
fn buffer(&self) -> &'static mut [u8][src]the underlying buffer
+fn claimed(&self) -> &'static AtomicUsize[src]How many characters were claimed so far.
+fn flush(&self, logs: &str)[src]Call the flusher.
+fn render(&self, record: &Record<'_>) -> &'static [u8][src]Actually render the arguments (via internal static buffer).
+A way to pass on logs, user supplied.
+In embedded, this is intended to pend an interrupt +to send the logs off via (USB) serial, semihosting, or similar.
+On PC, typical implemenation will just println! or eprintln!
+fn flush(&self, logs: &str)[src]Implementor must handle passed log &str in some hopefully useful way.
A way to format logs, user supplied.
+fn render<'a>(&self, buf: &'a mut [u8], record: &Record<'_>) -> &'a [u8][src]Implementor must render record into buf, returning the slice containing the rendered
+record.
impl Renderer for DefaultRenderer[src]impl Renderer for RipgrepRenderer[src]Trait for either state or statistics of loggers.
+fn attempts(&self) -> T[src]How often was one of the logging macros called.
+fn successes(&self) -> T[src]How often was one of the logging macros called without early exit (e.g., buffer not full)
+fn flushes(&self) -> T[src]How often was the flusher called.
+fn read(&self) -> T[src]How many bytes were flushed so far.
+fn written(&self) -> T[src]How many bytes were logged so far.
+Fallible, panic-free version of the log::Log trait.
The intention is actually that implementors of this trait also
+implement log::Log in a panic-free fashion, and simply drop logs
+that can't be logged. Because, if the user can handle the error, they
+would be using the fallible macros, and if not, they most likely do not
+want to crash.
fn try_log(&self, _: &Record<'_>) -> Result<(), ()>[src]Fallible logging call (fails when buffer is full)
+TryLog with some usage statistics on top.
+fn statistics(&self) -> Statistics[src]Read out statistics on logger usage.
+