remote_trait_object/
transport.rs

1//! Abstractions of a **transport** that carries out an actual communication for `remote-trait-object`.
2//!
3//! You have to implement these traits in your own requirement, to use `remote-trait-object` over them.
4//! It can be ordinary in-process communication, inter-process communication, or even networking over
5//! different machines.
6
7pub(crate) mod multiplex;
8
9/// An error that can be returned in [`send()`] or [`recv()`].
10///
11/// Note that only `Timeout` and `Termination` will be handled specially by the `remote-trait-object` context.
12/// All other errors must be wrapped as `Custom`, and it will be just conveyed to the user.
13///
14/// [`send()`]: trait.TransportSend.html#tymethod.send
15/// [`recv()`]: trait.TransportRecv.html#tymethod.recv
16#[derive(Clone, Debug, PartialEq)]
17pub enum TransportError {
18    /// An error that indicates that your call to `send()` or `recv()` can't be finished within the timeout you set.
19    TimeOut,
20
21    /// An error that indicates that you have called [`terminate()`] of the spawned [`Terminate`] from the object you're calling a method of.
22    ///
23    /// [`Terminate`]: trait.Terminate.html
24    /// [`terminate()`]: trait.Terminate.html#tymethod.terminate
25    Termination,
26
27    // TODO: Provide an appropriate type for this
28    /// An opaque error that will be just passed to the user.
29    Custom,
30}
31
32/// An abstraction of a sending half of the transport
33///
34/// All outgoing packets will be delivered to a single instance of this trait, which has been given
35/// when [`Context`] is created.
36///
37/// [`Context`]: ../struct.Context.html
38pub trait TransportSend: Sync + Send + std::fmt::Debug {
39    /// Sends a packet with an optional timeout.
40    fn send(&self, data: &[u8], timeout: Option<std::time::Duration>)
41        -> Result<(), TransportError>;
42
43    /// Creates a terminate switch that can be sent to another thread
44    fn create_terminator(&self) -> Box<dyn Terminate>;
45}
46
47/// An abstraction of a receiving half of the transport
48///
49/// All incoming packets will be delivered by a single instance of this trait, which has been given
50/// when [`Context`] is created.
51///
52/// [`Context`]: ../struct.Context.html
53pub trait TransportRecv: Send {
54    /// Receives a packet with an optional timeout.
55    ///
56    /// Note that it is not guaranteed to receive remaining data after the counter end has
57    /// been closed earlier. You should assume that you will receive Err(Custom) in such case.
58    fn recv(&self, timeout: Option<std::time::Duration>) -> Result<Vec<u8>, TransportError>;
59
60    /// Creates a terminate switch that can be sent to another thread
61    fn create_terminator(&self) -> Box<dyn Terminate>;
62}
63
64/// A switch that can be separately managed by another thread.
65///
66/// This is the only way to wake up a blocking [`send()`] or [`recv()`] by yourself. (Not by the other end)
67/// [`TransportSend`] and [`TransportRecv`] must be able to provide such a switch that triggers [`Termination`] error for its own [`send()`] or [`recv()`].
68///
69/// [`TransportSend`]: trait.TransportSend.html
70/// [`TransportRecv`]: trait.TransportRecv.html
71/// [`send()`]: trait.TransportSend.html#tymethod.send
72/// [`recv()`]: trait.TransportRecv.html#tymethod.recv
73/// [`Termination`]: enum.TransportError.html#variant.Termination
74pub trait Terminate: Send {
75    /// Wakes up block on recv() or send()
76    fn terminate(&self);
77}
remote_trait_object/transport.rs

remote_trait_object/
transport.rs
