tango/server/

mod.rs

//! This module provides a high-level access to the server-side of Tango.

mod def;

mod server;
mod class;
mod dev;
mod attr;
mod command;
mod history;
mod polling;

mod admin;
mod terminate;

#[cfg(feature = "cli")]
mod cli;

pub use def::{ClassDef, CommandDef, AttrDef};
pub use server::{Server, ServerBuilder, ServerHandle};
pub use terminate::terminate;
pub use class::Class;
pub use dev::Dev;
pub use command::Command;
pub use attr::Attr;

#[cfg(feature = "cli")]
pub use cli::ServerArgs;

use crate::dev::DevState;


/// What a device model has to be, gathering in one bound everything a server needs of it:
/// it is shared between the threads serving the requests.
///
/// A model is deleted by being given to the delete function of its class, see
/// [`ClassDef::delete`], which is where it releases what it holds: before every
/// initialization but the first, and once its device is no longer served. A model whose
/// server is dropped without being stopped, see [`Server::stop_async`], is never deleted, and
/// only dropped with the last reference to its device, which may be held long after. Its
/// [`Drop`] is therefore only relied upon to free memory, never to release its hardware or
/// anything else that the new model of a device restarted under the same name takes again.
///
/// Every such type is a model, there being nothing to implement: this is the bound the
/// definitions and the devices are written against rather than a trait a model opts into.
pub trait Model: Send + Sync + 'static {}
impl<T: Send + Sync + 'static> Model for T {}

/// The name of the attribute, and of the command, every device gives its state under.
const STATE_NAME: &str = "State";
/// The name of the attribute, and of the command, every device gives its status under.
const STATUS_NAME: &str = "Status";
/// The name of the command every device is initialized again by.
const INIT_NAME: &str = "Init";
/// The names of the attributes every device has whatever its class.
const RESERVED_ATTRS: &[&str] = &[STATE_NAME, STATUS_NAME];
/// The names of the commands every device has whatever its class.
const RESERVED_COMMANDS: &[&str] = &[STATE_NAME, STATUS_NAME, INIT_NAME];
/// The status of a device that has no model because it has not been initialized yet,
/// which every device is between the moment it is added and the moment it is synchronized.
const MISSING_STATUS: &str = "The device is not initialized";
/// The status of a device whose class derives no status of its own from the model.
const DEFAULT_STATUS: &str = "Device is on";
/// The state of a device whose class derives no state of its own from the model, which is
/// the one every device that has nothing to say of itself is in.
const DEFAULT_STATE: DevState = DevState::On;

/// How many readings the history of an attribute keeps unless set otherwise, see
/// [`Attr::set_history_depth`], which is the depth of the polling buffer of cppTango.
const DEFAULT_HISTORY_DEPTH: usize = 10;

/// The reserved name that name is, if it is one: the state, the status and the
/// initialization of a device are answered by the server itself, whatever its class and its
/// devices define, so anything defined under one of those names would never be reached.
/// 
/// Given back in the spelling of the reserved name rather than of the one that was asked
/// for, the two differing only by their case, so that a refusal can point at both.
fn reserved_name<'r>(name: &str, reserved: &'r [&'r str]) -> Option<&'r str> {
    reserved.iter().copied().find(|other| name.eq_ignore_ascii_case(other))
}