Trait Scope

Source

pub trait Scope:
    Send
    + Sync
    + Copy {
    // Required method
    fn init<S: Display>(
        name: S,
        level: Level,
        facade: FacadeVariant,
        options: Options,
    ) -> Result<()>;

    // Provided methods
    fn init_with_defaults<S: Display>(name: S) -> Result<()> { ... }
    fn logscope() -> ScopeKey { ... }
    fn default_options() -> Options { ... }
    fn default_facade() -> FacadeVariant { ... }
    fn default_level() -> Level { ... }
}

Expand description

Initialization trait for the log scope

Trait to initialize to library which is implemented on a set of LogKeys. It can either be implemented manually or derived from the HCLog derive macro from the hclog_macros crate. If the LOGCOMPAT option is set the compatibility logger is initialized as well.

A type implementing this trait has to implement Send, Sync and Copy.

§What is a Scope?

The Scope is a container to store all initialized LogKeys. Each Scope is assigned a unique ScopeKey which is used to crate a namespace for LogKeys in the context. This way can be ensured that there are no identifier collisions in different crates or modules when using the library.

A call to init will fetch a new ScopeKey from the context and initialize the loggers within this container. The ScopeKey itself is constant at runtime and can not be changed because it is used as an Index in the context.

§Options of the Scope

On initialization default Level, FacadeVariant and Options can be set for the Scope. This values are passed to each newly initialized LogKey in this Scope. If the LogKey is initialized with a different set of options, the default options are ignored.

§Examples

§Manual Implementation

use hclog::{Scope, Level, FacadeVariant, Options, Result};

#[derive(Copy, Clone, Debug)]
enum MyLogKeys {
  Foo,
  Bar,
  Baz,
}

// This example won't compile because the LogKeys and std::fmt::Display traits
// are not implemented but reqiuired. This is by intention to show the minimal
// implementation of the Scope trait.

impl Scope for MyLogKeys {
    fn init<S: std::fmt::Display>(
        name: S, level: Level, facade: FacadeVariant, options: Options
    ) -> Result<()> {
        hclog::init::<Self, S>(name, level, facade, options)?;
        hclog::add_submodules(&[Self::Foo, Self::Bar, Self::Baz])
    }
}

§Derive from `HCLog` via crate `hclog_macros`

For a detailed usage of the derive macro see the documentation of the crate hclog_macros.

use hclog_macros::HCLog;

#[derive(HCLog, Copy, Clone)]
enum MyLogKeys {
   Foo,
   Bar,
   Baz,
}

§Errors

The initialzation of the log scope can fail if:

the log scope is already initialized
the initialization of the log scope fails
the LOGCOMPAT option is set and the initialization of the compatibility logger fails

§Panics

The init or init_with_defaults function might panic if the internal RwLock is already held by the current thread as documented in std::sync::RwLock::write.

Required Methods§

Source

fn init<S: Display>( name: S, level: Level, facade: FacadeVariant, options: Options, ) -> Result<()>

Initialization function for the log scope

This function is intended to be called once from the application on the defined LogKey type. It initializes the library self - if not already happend - and creates a new Scope entry for the type it’s implemented on. The passed name is used as the name of the log scope and is displayed in the log output if the BINNAME Options is set. The level is the default Level for the loggers in this scope. The facade is the default FacadeVariant for the loggers in this scope.

Provided Methods§

Source

fn init_with_defaults<S: Display>(name: S) -> Result<()>

Shortcut to init which initialize the library with default values taken from the default_* functions. Those functions can be overwritten by the implementing type or are attributable via the hclog attribute macro from the hclog_macros crate.

Source