From 9e0c8e3d8bb3be793b459707dd7f7f599b8be7e7 Mon Sep 17 00:00:00 2001 From: arkpar Date: Wed, 30 Dec 2015 12:23:36 +0100 Subject: [PATCH] Documentation --- src/network/host.rs | 6 ++++++ src/network/mod.rs | 11 +++++++++-- src/network/service.rs | 4 ++++ 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/network/host.rs b/src/network/host.rs index 50954661c..3d8e78e46 100644 --- a/src/network/host.rs +++ b/src/network/host.rs @@ -191,6 +191,7 @@ impl Encodable for CapabilityInfo { } } +/// IO access point pub struct HostIo<'s> { protocol: ProtocolId, connections: &'s mut Slab, @@ -210,6 +211,7 @@ impl<'s> HostIo<'s> { } } + /// Send a packet over the network to another peer. pub fn send(&mut self, peer: PeerId, packet_id: PacketId, data: Vec) -> Result<(), Error> { match self.connections.get_mut(Token(peer)) { Some(&mut ConnectionEntry::Session(ref mut s)) => { @@ -224,6 +226,7 @@ impl<'s> HostIo<'s> { Ok(()) } + /// Respond to a current network message. Panics if no there is no packet in the context. pub fn respond(&mut self, packet_id: PacketId, data: Vec) -> Result<(), Error> { match self.session { Some(session) => self.send(session.as_usize(), packet_id, data), @@ -233,6 +236,7 @@ impl<'s> HostIo<'s> { } } + /// Register a new IO timer. Returns a new timer toke. 'ProtocolHandler::timeout' will be called with the token. pub fn register_timer(&mut self, ms: u64) -> Result{ match self.timers.insert(UserTimer { delay: ms, @@ -246,6 +250,7 @@ impl<'s> HostIo<'s> { } } + /// Broadcast a message to other IO clients pub fn message(&mut self, id: UserMessageId, data: Option>) { match self.event_loop.channel().send(HostMessage::UserMessage(UserMessage { protocol: self.protocol, @@ -257,6 +262,7 @@ impl<'s> HostIo<'s> { } } + /// Disable current protocol capability for given peer. If no capabilities left peer gets disconnected. pub fn disable_peer(&mut self, _peer: PeerId) { //TODO: remove capability, disconnect if no capabilities left } diff --git a/src/network/mod.rs b/src/network/mod.rs index b3e922172..c44182430 100644 --- a/src/network/mod.rs +++ b/src/network/mod.rs @@ -77,16 +77,23 @@ pub type HandlerIo<'s> = host::HostIo<'s>; pub type Message = host::UserMessage; pub type MessageId = host::UserMessageId; +/// Network IO protocol handler. This needs to be implemented for each new subprotocol. +/// TODO: Separate p2p networking IO from IPC IO. `timeout` and `message` should go to a more genera IO provider. +/// All the handler function are called from within IO event loop. pub trait ProtocolHandler: Send { + /// Initialize the hadler fn initialize(&mut self, io: &mut HandlerIo); + /// Called when new network packet received. fn read(&mut self, io: &mut HandlerIo, peer: &PeerId, packet_id: u8, data: &[u8]); + /// Called when new peer is connected. Only called when peer supports the same protocol. fn connected(&mut self, io: &mut HandlerIo, peer: &PeerId); + /// Called when a previously connected peer disconnects. fn disconnected(&mut self, io: &mut HandlerIo, peer: &PeerId); + /// Timer function called after a timeout created with `HandlerIo::timeout`. fn timeout(&mut self, io: &mut HandlerIo, timer: TimerToken); + /// Called when a broadcasted message is received. The message can only be sent from a different protocol handler. fn message(&mut self, io: &mut HandlerIo, message: &Message); } -pub struct NetworkClient; pub type NetworkService = service::NetworkService; - diff --git a/src/network/service.rs b/src/network/service.rs index 1e245c20b..986d6dd11 100644 --- a/src/network/service.rs +++ b/src/network/service.rs @@ -5,12 +5,14 @@ use mio::*; use network::{Error, ProtocolHandler}; use network::host::{Host, HostMessage, PeerId, PacketId, ProtocolId}; +/// IO Service with networking pub struct NetworkService { thread: Option>, host_channel: Sender } impl NetworkService { + /// Starts IO event loop pub fn start() -> Result { let mut event_loop = EventLoop::new().unwrap(); let channel = event_loop.channel(); @@ -23,6 +25,7 @@ impl NetworkService { }) } + /// Send a message over the network. Normaly `HostIo::send` should be used. This can be used from non-io threads. pub fn send(&mut self, peer: &PeerId, packet_id: PacketId, protocol: ProtocolId, data: &[u8]) -> Result<(), Error> { try!(self.host_channel.send(HostMessage::Send { peer: *peer, @@ -33,6 +36,7 @@ impl NetworkService { Ok(()) } + /// Regiter a new protocol handler with the event loop. pub fn register_protocol(&mut self, handler: Box, protocol: ProtocolId, versions: &[u8]) -> Result<(), Error> { try!(self.host_channel.send(HostMessage::AddHandler { handler: handler,