Documentation

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<ConnectionEntry>,
@@ -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<u8>) -> 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<u8>) -> 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<TimerToken, Error>{
 		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<Vec<u8>>) {
 		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
 	}

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

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<JoinHandle<()>>,
 	host_channel: Sender<HostMessage>
 }
 
 impl NetworkService {
+	/// Starts IO event loop
 	pub fn start() -> Result<NetworkService, Error> {
 		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<ProtocolHandler+Send>, protocol: ProtocolId, versions: &[u8]) -> Result<(), Error> {
 		try!(self.host_channel.send(HostMessage::AddHandler {
 			handler: handler,