Crate alarm 

alarm provides a series of alarm facilities, that can be used when creating alarm system functionality.

A lightweight alarm facade.

The alarm crate provides a single alarm API that abstracts over the actual alarm implementation/manifestation. Libraries can use the alarm API provided by this crate, and the consumer of those libraries can choose the alarm implementation that is most suitable for its use case.

If no alarm implementation is selected, the facade falls back to a “noop” implementation that ignores all alarm messages. The overhead in this case is very small - just an integer load, comparison and jump.

An alarm request consists of a target, a priority, a frequency, and a message. A target is a string which defaults to the module path of the location of the alarm request, though that default may be overridden. Alarm implementations typically use the target to filter requests based on some user configuration.

Usage

The basic use of the alarm crate is through the four alert macros: [critical_alarm!], [high_alarm!], [medium_alarm!], and [low_alarm!] where critical_alarm! represents the highest-priority alarm messages and low_alarm! the lowest. The alarm messages are filtered by configuring the alarm priority to exclude alarms with a lower priority. Each of these macros accept format strings similarly to println!.

How to use in libraries

Libraries should link only to the alarm crate, and use the provided macros to arm alarms with whatever information will be useful to downstream consumers.

Examples

use alarm::{critical_alarm, low_alarm};
use log::{info, warn};

pub fn shave_the_yak(yak: &mut Yak) {
    critical_alarm!()
    info!(target: "yak_events", "Commencing yak shaving for {yak:?}");

    loop {
        match find_a_razor() {
            Ok(razor) => {
                info!("Razor located: {razor}");
                yak.shave(razor);
                break;
            }
            Err(err) => {
                warn!("Unable to locate a razor: {err}, retrying");
            }
        }
    }
}

Structs

Alarm

Struct representing a single alarm

Enums

Frequency

Enum used to set how often an active alarm should trigger until turned off.

Priority

Enum used to represent the priority of an individual alarm signal. An alarm of Medium priority will override an alarm of Low priority, and so on.

State

The state of an alarm.

Traits

Trigger

Trait used to have a common interface to trigger an alarm.