rstango 0.3.0

//! 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 admin;
mod signal;

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

pub use def::{ClassDef, CommandDef, AttrDef};
pub use server::{Server, ServerBuilder, ServerHandle};
pub use class::{AnyClass, Class};
pub use dev::{AnyDev, Dev};
pub use command::Command;
pub use attr::Attr;
#[cfg(feature = "cli")]
pub use cli::ServerArgs;

use std::marker::PhantomData;
use std::fmt::{self, Debug};
use std::ops::Deref;
use std::sync::{Arc, Weak};

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, and it lives as long as the
/// class it belongs to, which is as long as the server serving it.
///
/// 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;

/// 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))
}

/// A reference to something a server owns, which derefs to it but never gives out the
/// [`Arc`] it holds, and borrows what it was given by: this is what keeps the users of a
/// server from keeping any of it alive past the shutdown of that server, since ownership
/// is cyclic and only broken by that shutdown, see [`server::ServerHandle`].
pub struct Ref<'a, T: ?Sized> {
    inner: Arc<T>,
    _borrow: PhantomData<&'a T>,
}

impl<T: ?Sized> Ref<'_, T> {

    #[inline]
    pub(super) fn new(inner: Arc<T>) -> Self {
        Self { inner, _borrow: PhantomData }
    }

    /// A weak reference to what this refers to, see [`WeakRef`]. This is an associated
    /// function, as [`Arc::downgrade`] is, so that it never hides a method of the target.
    #[inline]
    pub fn downgrade(this: &Self) -> WeakRef<T> {
        WeakRef { inner: Arc::downgrade(&this.inner) }
    }

}

impl<T: ?Sized> Deref for Ref<'_, T> {
    type Target = T;
    #[inline]
    fn deref(&self) -> &T {
        &self.inner
    }
}

impl<T: ?Sized + Debug> Debug for Ref<'_, T> {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        Debug::fmt(&*self.inner, f)
    }
}

/// A weak reference to something a server owns, see [`Ref::downgrade`], which keeps
/// nothing of it alive and can therefore be kept anywhere, a thread of its own in
/// particular. What it upgrades into is a [`Ref`] borrowed from it, so that it is only held
/// for as long as it is used.
///
/// It is tied to that very thing: a device removed, or replaced by a restart under the
/// same name, no longer upgrades, which is what tells a thread it started to stop.
pub struct WeakRef<T: ?Sized> {
    inner: Weak<T>,
}

impl<T: ?Sized> WeakRef<T> {

    /// What this refers to, if it is still there.
    #[inline]
    pub fn upgrade(&self) -> Option<Ref<'_, T>> {
        self.inner.upgrade().map(Ref::new)
    }

}

impl<T: ?Sized> Clone for WeakRef<T> {
    #[inline]
    fn clone(&self) -> Self {
        Self { inner: self.inner.clone() }
    }
}

impl<T: ?Sized> Debug for WeakRef<T> {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("(WeakRef)")
    }
}