memfault-ssf 1.25.2

Supporting crate for the Memfault memfaultd embedded Linux agent
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//
// Copyright (c) Memfault, Inc.
// See License.txt for details
//! Simple Service Framework
//!
//! This library provides a simple abstraction to implement a service oriented
//! architecture in a non-async Rust program.
//!
//! Each service runs in its own thread with a processing loop waiting on a
//! channel.
//!
//! This library provides a few essential traits:
//!
//! - `Service`: a trait implemented by services
//! - `Message`: a trait implemented by messages
//! - `Handler<M: Message>`: a trait implemented by services that can handle
//!   messages of type `M`.
//!
//! We provide some important structs to deploy the services:
//! - `ServiceThread`: will start and run a service inside a dedicated thread.
//!   It returns a `Mailbox`.
//! - `Mailbox<S: Service>`: a lightweight (cheap to `clone()`) handle to send
//!   messages to a thread.
//! - `Scheduler`: a utility thread which keeps a schedule of messages that need
//!   to be sent at fixed intervals.
//!
//! As well as important testing utilities that are a big part of the value
//! provided by this framework:
//! - `ServiceJig`: a way to run a service inside a test without using threads.
//!   The test can precisely decide when messages should be delivered and inspect
//!   the state of the service at any time.
//! - `ServiceMock`: a service mock. Use this when you just need a place where
//!   to send messages. Your test can then verify that the right messages were
//!   sent to the mock.
//!

use std::any::Any;

mod envelope;
mod mailbox;
mod msg_mailbox;
mod scheduler;
mod service_jig;
mod service_manager;
mod service_mock;
mod service_thread;
mod shared_service_thread;
mod stats;
mod system_messages;

pub use envelope::*;
use futures::future::LocalBoxFuture;
pub use mailbox::*;
pub use msg_mailbox::*;
pub use scheduler::*;
pub use service_jig::*;
pub use service_manager::*;
pub use service_mock::*;
pub use service_thread::*;
pub use shared_service_thread::*;
pub use stats::*;
pub use system_messages::*;

/// All services should implement this trait. It guarantees that we will be able
/// to run the service inside a thread (it is `Send`).
pub trait Service {
    fn name(&self) -> &str;
}

/// Implement this trait if your service needs to run a task in the background.
///
/// The implementation here does not need to be `Send` as we only run the
/// task on a single thread executor.
pub trait TaskService: Service {
    fn init(&mut self) -> LocalBoxFuture<'_, Result<(), String>> {
        Box::pin(async { Ok(()) })
    }
    fn run_task(&mut self) -> LocalBoxFuture<'_, Result<(), String>>;
}

/// Any type that will be sent between services needs to implement this trait.
///
/// Sending a Reply is optional (use `type Reply = ()` if you will not send a reply).
pub trait Message: Send + Sync + Any + 'static {
    type Reply: Send;
}

/// Implement this trait to indicate that your service can process a specific message.
///
/// The `deliver()` method is passed a `&mut self` reference to the service,
/// making it very easy to update your state. You can optionally include a
/// reply.
pub trait Handler<M: Message> {
    fn deliver(&mut self, m: M) -> M::Reply;
}

/// Blanket implementation of Message for any Vec<M>. You lose the return value.
impl<M: Message> Message for Vec<M> {
    type Reply = ();
}

/// Blanket implementation of delivering a `Vec<Message>` to a `Handler<Message>`.
impl<M: Message, S: Handler<M>> Handler<Vec<M>> for S {
    fn deliver(&mut self, messages: Vec<M>) {
        for m in messages {
            self.deliver(m);
        }
    }
}