engine-api.txt

pub trait Engine: Decompose + Send + Vertex + Unpin + 'static {
    /// Turn the Engine into an executable `Future`
    fn activate<'a>(self: Pin<&'a mut Self>) -> BoxFuture<'a, EngineResult>;

    /// Returns a text description of the engine.
    fn description(self: Pin<&Self>) -> String;

    /// Returns the progress tracker, which implies the future work.
    fn tracker(self: Pin<&mut Self>) -> &mut Indicator;

    /// Asks the engine to updates its local storage pointer.
    ///
    /// # Warning
    ///
    /// EngineLocalStorage is only accessed from a thread/runtime at a time. There should be no
    /// concurrent access to it. But since Engine can be moved between Runtimes, the local storage
    /// could be read from different threads _at different times_ (i.e., _Send_).
    ///
    /// The user must ensure their storage type are _Send_.
    #[inline]
    fn set_els(self: Pin<&mut Self>) {
        // empty default impl
    }

    /// Handle request sent by the network operator.
    #[inline]
    fn handle_request(&mut self, _request: Vec<u8>, _cred: UCred) -> Result<()> {
        Ok(())
    }

    /// NOTE(wyj): temporary API
    /// engines should not have thread/runtime local states in the fugture
    /// Preform preparatory work before detaching the engine from runtime
    /// e.g., clean thread-local states
    #[inline]
    fn pre_detach(&mut self) -> Result<()> {
        // empty default impl
        Ok(())
    }
}

Basic
description()      Returns a text description of the engine.

tracker()          Returns the progress tracker, which implies the future work.

set_els()		   Asks the engine to updates its local storage pointer.

Elements
input/output_queue(port_number)  Returns the a peer engine's queue for
receiving/sending RPC descriptors.

handle_request(bytes, user_id)   Handle a control path request.

Upgrade
flush()            Flushing the data and command queues.

decompose()        Decompose the engines to compositional state.

restore(state)          Create an engine from decomposed state.

check_compatible(v1, v2) Returns whether two version of an engine are compatible.

Future
poll()             Attempt to make some progress.