yuurei/src/service.rs

//! Session services
use super::*;
use tokio::{
    task::JoinHandle,
    sync::{
	mpsc,
	broadcast,
    },
};
use std::{fmt,error};
use std::marker::{Send,Sync};

///// A boxed message that can be downcasted.
//pub type BoxedMessage = Box<dyn std::any::Any + Send + Sync + 'static>;

/// A handle to a service.
pub trait Service<T=()>
    where T: Send + 'static
{
    /// The message type to send to the service.
    type Message: Send + Sync + 'static;
    /// The response to expect from the service.
    type Response: Send + Sync + 'static;
    
    /// Return the wait handle.
    ///
    /// This method should drop the message pipeline.
    fn wait_on(self) -> JoinHandle<T>;

    /// An immutable reference to the pipe for sending message. Useful for service handle detaching (i.e. cloning the message input pipe).
    fn message_in_ref(&self) -> &mpsc::Sender<Self::Message>;
    
    /// The message pipe for sending messages to the service.
    fn message_in(&mut self) -> &mut mpsc::Sender<Self::Message>;
    /// The message pipe for receiving messages from the service.
    fn message_out(&mut self) -> &mut broadcast::Receiver<Self::Response>;
    
    /// Is the service alive? A `None` value means 'maybe', and is the default return.
    ///
    /// # Note
    /// This should not be considered an infallible indicator of if the service has crashed or not. A better method is attempting to send or receive a message and the sender/receiver returning an error.
    #[inline] fn is_alive(&self) -> Option<bool>
    {
	None
    }
}

/// Error returned when subscribing to a service
#[derive(Debug)]
#[non_exhaustive]
pub enum SubscribeError
{
    /// The service's receive has already been dropped.
    SenderDropped,
    /// The service dropped the response oneshot channel.
    NoResponse,
}

impl error::Error for SubscribeError{}
impl fmt::Display for SubscribeError
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
    {
	match self {
	    Self::SenderDropped => write!(f, "the service has already stopped"),
	    Self::NoResponse => write!(f, "the service declined to, or was unable to respond"),
	}
    }
}