Struct middleman::Middleman

pub struct Middleman { /* fields omitted */ }

Methods

impl Middleman

pub fn new(stream: TcpStream) -> Middleman

Create a new Middleman structure to wrap the given Mio TcpStream. The Middleman implements mio::Evented, but delegates its functions to this given stream As such, registering the Middleman and registering the TcpStream are anaologous.

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

Write the given message directly into the TcpStream. Returns Err variant if there is a problem serializing or writing the message. The call returns Ok(()) once the bytes are entirely written to the stream.

pub fn send_packed(&mut self, msg: &PackedMessage) -> Result<(), Error>

See send. This variant can be useful to avoid the overhead of repeatedly packing a message for whatever reason, eg: sending the same message using multiple Middleman structs.

Note that this function does NOT check for internal consistency of the packed message. So, if this message was constructed by a means other than Packed::new, then the results may be unpredictable.

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>, 

Conume an iterator over some Message structs, sending them all in the order traversed (see send). Returns (a,b) where a gives the total number of messages sent successfully and where b is Ok if nothing goes wrong and an error otherwise. In the event of the first error, no more messages will be sent.

pub fn send_all_packed<'m, I>(
    &'m mut self,
    packed_msg_iter: I
) -> (usize, Result<(), Error>) where
    I: Iterator<Item = &'m PackedMessage>, 

See send_all and send_packed. This uses the message iterator from the former and the packed messages from the latter.

pub fn 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.

NOTE: The correctness of this call depends on the sender sending an internally consistent PackedMessage. If you (or the sender) are manually manipulating the internal state of sent messages this may cause errors for the receiver. If you are sticking to the Middleman API and treating each PackedMessage as a black box, everything should be fine.

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

See recv. Will repeatedly call recv() until the next message is not yet ready. Recevied messages are placed into the buffer dest_vector. The return result is (a,b) where a is the total number of message successfully received and where b is OK(()) if all goes well and some Err otherwise. In the event of the first error, the call will return and not receive any further.

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 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 recv_blocking_solo<M: Message>(
    &mut self,
    poll: &Poll,
    events: &mut Events,
    timeout: Option<Duration>
) -> Result<Option<M>, RecvError>

See recv_blocking. This function is intended as an alternative for use for cases where it is certain that this Middleman is the only registered mio::Evented for the provided Poll and Events objects. Thus, the call WILL NOT CHECK the token at all, presuming that all events are associated with this middleman.

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

Similar to recv_all_into, but rather than storing each received message 'm', the provided function is called with arguments (self, m) where self is &mut self. This allows for ergonomic utility of the received messages using a closure.

pub fn recv_all_packed_map<F>(
    &mut self,
    func: F
) -> (usize, Result<(), RecvError>) where
    F: FnMut(&mut Self, PackedMessage) + Sized, 

Combination of recv_all_map and recv_packed.

pub fn recv_packed(&mut self) -> Result<Option<PackedMessage>, RecvError>

Similar to recv, except builds (instead of some M: Message), a PackedMessage object. These packed messages can be deserialized later, sent on the line without knowledge of the message type etc.

pub fn peek_packed(&mut self) -> Result<Option<PackedMessage>, RecvError>

Similar to recv_packed, but the potentially-read bytes are not actually removed from the stream. The message will still be there.

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