Struct middleman::Middleman

pub struct Middleman { /* fields omitted */ }

Wraps a mio::TcpStream object. Implmenents mio::Evented so it can be registered for polling. Offers try_read and send functions primarily with variants for convenience. This structure doesn't involve any extra threading.

Note that data will only travel over the stream when read_in and write_out are called. Typically, these calls are agglutinated using the single call read_write in the context of a mio::Event. See the tests for some examples.

Methods

impl Middleman

pub fn new(stream: TcpStream) -> Middleman

Wraps the given mio::TcpStream in a new middleman.

pub fn read_write(&mut self, event: &Event) -> Result<(), Error>

This call is the bread and butter of reading and writing local changes to the middleman's internal state to the TcpStream within. If this function is never called, no progress will ever be made.

pub fn write_out(&mut self) -> Result<usize, Error>

Force the middleman to try and write any waiting bytes to the TcpStream. Instead of blocking when the socket isn't ready, the call returns Ok(0). Errors in writing to the socket emerge as an Err(_) variant.

It is advised to rely on the read_write for reading and writing instead.

pub fn read_in(&mut self) -> Result<usize, Error>

Force the middleman to try and read bytes from the inner TcpStream. Instead of blocking when the socket isn't ready, the call returns Ok(0). Errors in reading from the socket emerge as an Err(_) variant.

It is advised to rely on the read_write for reading and writing instead.

pub fn send<M: Message>(&mut self, m: &M) -> Result<(), SendError>

Serialize the given Message, and store it internally for writing to the socket later. This call will return Err(_) if serialization of the message fails, or the serialized representation is too large for the Middleman to represent (Structures are required to have a serialized representation no larger than std::u32::MAX).

Note that each send() call may serialize an entirely different type of structure. Be careful using this feature, as any receive calls on the other end expecting a different type may fail to read (at best) or erroniously produce valid (albeit undefined) data silently at worst.

pub fn send_all<'m, I, M>(
    &'m mut self,
    msg_iter: I
) -> (usize, Result<(), SendError>) where
    M: Message + 'm,
    I: Iterator<Item = &'m M>, 

Given some iterator over Message structs, sends them each in sequence. The return result is a tuple (a, b) where a gives the number of messages sent successfully, and b returns Err(_) with an error if something goes wrong.

After encountering the first error, the iteration will cease and the offending message will not be sent.

pub fn try_discard(&mut self) -> bool

Attempt to read one message worth of bytes from the input buffer and discard it This operation doesn't require knowing the type of the struct. As such, this can be used to discard a message if somehow it is unserializable.

pub fn try_recv<M: Message>(&mut self) -> Result<Option<M>, RecvError>

Attempt to dedserialize some data in the receiving buffer into a single complete structure with the given type M. If there is insufficient data at the moment, Ok(None) is returned.

As the type is provided by the reader, it is possible for the sent message to be misinterpreted as a different type. At best, this is detected by a failure in deserialization. If an error occurs, the data is not consumed from the Middleman. Subsequent reads will operate on the same data.

pub fn try_recv_all<M: Message>(
    &mut self,
    dest_vector: &mut Vec<M>
) -> (usize, Result<(), RecvError>)

Keep attempting to call try_recv until the next message is no longer ready. Will push received messages into the provided destination buffer in the order received. See try_recv for more information.

Returns (a, b) where a is the number of messages successfully received and b is Err(_) if an error occurs attempting to deserialize a message. Upon the first error, no further messages nor the offending message are recieved or removed from the buffer. Subsequent recv() calls will thus operate on the same data that caused the error before.

pub fn recv_blocking<M: Message>(
    &mut self,
    poll: &Poll,
    events: &mut Events,
    my_tok: Token,
    extra_events: &mut Vec<Event>,
    timeout: Option<Duration>
) -> Result<Option<M>, RecvError>

Hijack the mio event loop, reading and writing to the socket as polling allows. Events not related to the recv() of this middleman (determined from the provided mio::Token) are pushed into the provided extra_events vector. Returns Ok(Some(_)) if a message was successfully received. May return Ok(None) if the user provides as timeout some non-none Duration. Returns Err(_) if something goes wrong with reading from the socket or deserializing the message. See try_recv for more information.

WARNING: The user should take care to iterate over these events also, as without them all the Evented objects registered with the provided poll object might experience lost wakeups. It is suggested that in the event of any recv_blocking calls in your loop, you extend the event loop with a drain() on the same vector passed here as extra_events (using the iterator chain function, for example.)

pub fn try_recv_all_map<F, M>(
    &mut self,
    func: F
) -> (usize, Result<(), RecvError>) where
    M: Message,
    F: FnMut(M) + Sized, 

A convenience function similar to try_recv_all, but instead calls a provided function for each successfully received message instead of pushing them to a provided buffer. See try_recv_all and try_recv for moree information

pub fn recv_ready(&mut self) -> bool

Returns true if the internal buffer current holds 1+ messages, ready to be received. In this case, try_recv and similar functions are guaranteed to return a message.

pub fn try_recv_bytes(&mut self, dest_buffer: &mut Vec<u8>) -> Option<u32>

Attempts to read a message from the internal buffer, just like try_recv, but instead makes no attempt to deserialize the struct data. Instead, bytes are appended to the provided byte buffer. For this reason, no type annotation is required.

pub fn try_peek<M: Message>(&mut self) -> Result<Option<M>, RecvError>

Similar to try_recv, whether or not the call succeeds, the data is not removed from the internal buffer. Subsequent calls will thus repeatedely deserialize the same bytes.

Trait Implementations

impl Debug for Middleman

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Evented for Middleman

fn register(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<()>

Register self with the given Poll instance.

fn reregister(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<()>

Re-register self with the given Poll instance.

fn deregister(&self, poll: &Poll) -> Result<()>

Deregister self from the given Poll instance