drmem_api/
lib.rs

1//! This crate is used by internal tasks of `drmemd` as well as
2//! hardware drivers.
3//!
4//! The interfaces and types defined in this crate are useful for
5//! those wishing to write a new back-end storage module or a driver
6//! for the `drmemd` executable.
7
8use async_trait::async_trait;
9use chrono::*;
10
11mod types;
12
13// Pull types down to the `drmem-api` namespace.
14
15pub use types::device;
16pub use types::Error;
17
18/// A specialization of `std::result::Result<>` where the error value
19/// is `types::Error`.
20
21pub type Result<T> = std::result::Result<T, Error>;
22
23/// Defines the trait that a back-end needs to implement to provide
24/// storage for -- and access to -- the state of each driver's
25/// devices.
26
27#[async_trait]
28pub trait Store {
29    /// Called when a read-only device is to be registered with the
30    /// back-end.
31    ///
32    /// When `drmemd` begins, it starts up the set of drivers
33    /// specified in the configuration file. As these drivers
34    /// initialize, they'll register the devices they need. For
35    /// read-only devices, this method will be called.
36    ///
37    /// - `driver` is the name of the driver. The framework will
38    ///   guarantee that this parameter is consistent for all devices
39    ///   defined by a driver.
40    /// - `name` is the full name of the device.
41    /// - `units` is an optional value which specifies the engineering
42    ///   units returned by the device.
43    /// - `max_history` is a hint as to how large an archive the user
44    ///   specifies should be used for this device.
45    ///
46    /// On success, this function returns a pair. The first element is
47    /// a closure the driver uses to report updates. The second
48    /// element is an optional value representing the last value of
49    /// the device, as saved in the back-end.
50
51    async fn register_read_only_device(
52        &mut self,
53        driver: &str,
54        name: &types::device::Name,
55        units: Option<&String>,
56        max_history: Option<usize>,
57    ) -> Result<(
58        driver::ReportReading<types::device::Value>,
59        Option<types::device::Value>,
60    )>;
61
62    /// Called when a read-write device is to be registered with the
63    /// back-end.
64    ///
65    /// When `drmemd` begins, it starts up the set of drivers
66    /// specified in the configuration file. As these drivers
67    /// initialize, they'll register the devices they need. For
68    /// read-write devices, this method will be called.
69    ///
70    /// - `driver` is the name of the driver. The framework will
71    ///   guarantee that this parameter is consistent for all devices
72    ///   defined by a driver.
73    /// - `name` is the full name of the device.
74    /// - `units` is an optional value which specifies the engineering
75    ///   units returned by the device.
76    /// - `max_history` is a hint as to how large an archive the user
77    ///   specifies should be used for this device.
78    ///
79    /// On success, this function returns a 3-tuple. The first element
80    /// is a closure the driver uses to report updates. The second
81    /// element is a handle with which the driver will receive setting
82    /// requests. The third element is an optional value representing
83    /// the last value of the device, as saved in the back-end.
84
85    async fn register_read_write_device(
86        &mut self,
87        driver: &str,
88        name: &types::device::Name,
89        units: Option<&String>,
90        max_history: Option<usize>,
91    ) -> Result<(
92        driver::ReportReading<types::device::Value>,
93        driver::RxDeviceSetting,
94        Option<types::device::Value>,
95    )>;
96
97    /// Called when information from a device is requested.
98    ///
99    /// On success, this method should return an array of
100    /// `client::DevInfoReply` data. If a `pattern` is specified, only
101    /// device names matching the pattern should be returned. The
102    /// grammar of the pattern is the one used by Redis (to be
103    /// consistent across back-ends.)
104
105    async fn get_device_info(
106        &mut self,
107        pattern: Option<&str>,
108    ) -> Result<Vec<client::DevInfoReply>>;
109
110    /// Sends a request to a driver to set its device to the specified
111    /// value.
112
113    async fn set_device(
114        &self,
115        name: types::device::Name,
116        value: types::device::Value,
117    ) -> Result<types::device::Value>;
118
119    /// Obtains the `mpsc::Sender<>` handle associated with the
120    /// specified device. This handle can be used to send settings to
121    /// the device. If 'own` is set to `true`, the requester will be
122    /// the only one that can send settings to the device. NOTE: `own`
123    /// is currently unsupported and should always be set to
124    /// 'false'. When it gets supported, requesters can decide whether
125    /// they should set it to true.
126
127    async fn get_setting_chan(
128        &self,
129        name: types::device::Name,
130        own: bool,
131    ) -> Result<driver::TxDeviceSetting>;
132
133    /// Creates a stream that yields values of a device as it updates.
134
135    async fn monitor_device(
136        &mut self,
137        name: types::device::Name,
138        start: Option<DateTime<Utc>>,
139        end: Option<DateTime<Utc>>,
140    ) -> Result<types::device::DataStream<types::device::Reading>>;
141}
142
143pub mod client;
144pub mod driver;
drmem_api/lib.rs

drmem_api/
lib.rs
