diff --git a/diode-file-bindings/src/lib.rs b/diode-file-bindings/src/lib.rs index d7e01ee..8623e42 100644 --- a/diode-file-bindings/src/lib.rs +++ b/diode-file-bindings/src/lib.rs @@ -9,6 +9,9 @@ use std::{ str::FromStr, }; +/// # Panics +/// +/// Will return `Err` if ip and port cannot be parsed. #[unsafe(no_mangle)] #[allow(clippy::missing_safety_doc)] pub unsafe extern "C" fn diode_new_config( @@ -41,6 +44,9 @@ pub unsafe extern "C" fn diode_free_config(ptr: *mut file::Config, output_dir: &path::Path, diff --git a/src/aux/file/send.rs b/src/aux/file/send.rs index 6f64b52..bc7bcbc 100644 --- a/src/aux/file/send.rs +++ b/src/aux/file/send.rs @@ -10,6 +10,10 @@ use std::{ path, }; +/// # Errors +/// +/// Will return `Err` if `send_file` function +/// returns an `Err`. pub fn send_files( config: &file::Config, files: &[String], @@ -21,6 +25,13 @@ pub fn send_files( Ok(()) } +/// # Errors +/// +/// Will return `Err` if: +/// - `net::TcpStream::connect(socket_addr)?` +/// or +/// - `unix::net::UnixStream::connect(path)?` +/// fails. pub fn send_file( config: &file::Config, file_path: &String, diff --git a/src/aux/udp/receive.rs b/src/aux/udp/receive.rs index 017aa38..c3c2e7f 100644 --- a/src/aux/udp/receive.rs +++ b/src/aux/udp/receive.rs @@ -73,6 +73,10 @@ fn receive_tcp_loop( } } +/// # Errors +/// +/// Will return `Err` if `from_unix` `PathBuf` +/// already exists. pub fn receive( config: &udp::Config, to_udp_bind: net::SocketAddr, diff --git a/src/aux/udp/send.rs b/src/aux/udp/send.rs index 2da9c5f..475b565 100644 --- a/src/aux/udp/send.rs +++ b/src/aux/udp/send.rs @@ -30,6 +30,13 @@ where } } +/// # Errors +/// +/// Will return `Err` if: +/// - `net::TcpStream::connect(socket_addr)?` +/// or +/// - `unix::net::UnixStream::connect(path)?` +/// fails. pub fn send( config: &udp::Config, from_udp: net::SocketAddr, diff --git a/src/lib.rs b/src/lib.rs index d699278..cccccf5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,6 +12,10 @@ mod sock_utils; #[allow(unsafe_code)] mod udp; +/// # Errors +/// +/// Will return `Err` if `file` cannot be opened +/// or logger cannot be set (Term or file mode). pub fn init_logger( level_filter: log::LevelFilter, file: Option, diff --git a/src/protocol.rs b/src/protocol.rs index e67083d..cdd472e 100644 --- a/src/protocol.rs +++ b/src/protocol.rs @@ -77,6 +77,11 @@ pub struct RaptorQ { } impl RaptorQ { + /// # Errors + /// + /// Will return `Err` if `symbol_count` + /// or + /// `nb_repair_packets` parsing fails pub fn new(mtu: u16, block_size: u32, repair_percentage: u32) -> Result { let mut max_packet_size = mtu - PACKET_HEADER_SIZE - RAPTORQ_HEADER_SIZE; max_packet_size -= max_packet_size % RAPTORQ_ALIGNMENT; @@ -110,18 +115,22 @@ impl RaptorQ { }) } + #[must_use] pub const fn block_size(&self) -> u32 { self.transfer_length } + #[must_use] pub const fn min_nb_packets(&self) -> u16 { self.symbol_count } + #[must_use] pub fn nb_packets(&self) -> u32 { u32::from(self.symbol_count) + u32::from(self.nb_repair_packets) } + #[must_use] pub fn encode(&self, block_id: u8, data: &[u8]) -> Vec { let encoder = raptorq::SourceBlockEncoder::with_encoding_plan( block_id, @@ -139,6 +148,7 @@ impl RaptorQ { packets } + #[must_use] pub fn decode(&self, block_id: u8, packets: Vec) -> Option> { let mut decoder = raptorq::SourceBlockDecoder::new( block_id, diff --git a/src/receive/mod.rs b/src/receive/mod.rs index 2dc8be7..f60c52c 100644 --- a/src/receive/mod.rs +++ b/src/receive/mod.rs @@ -172,6 +172,10 @@ where ClientEnd: Send + Sync + Fn(C, bool), E: Into, { + /// # Errors + /// + /// Will return `Err` if `multiplex_control` semaphore + /// cannot be created. pub fn new( config: Config, raptorq: protocol::RaptorQ, @@ -203,6 +207,9 @@ where }) } + /// # Errors + /// + /// Will return `Err` if scoped threads cannot spawned. #[allow(clippy::too_many_lines)] pub fn start<'a>(&'a self, scope: &'a thread::Scope<'a, '_>) -> Result<(), Error> { log::info!( diff --git a/src/send/mod.rs b/src/send/mod.rs index 07be5e7..74d3f98 100644 --- a/src/send/mod.rs +++ b/src/send/mod.rs @@ -123,6 +123,10 @@ impl Sender where C: Read + AsRawFd + Send, { + /// # Errors + /// + /// Will return `Err` if `multiplex_control` semaphore + /// cannot be created. pub fn new(config: Config, raptorq: protocol::RaptorQ) -> Result { let multiplex_control = semka::Sem::new(config.max_clients) .ok_or(Error::Other("failed to create semaphore".into()))?; @@ -151,6 +155,9 @@ where }) } + /// # Errors + /// + /// Will return `Err` if scoped threads cannot spawned. pub fn start<'a>(&'a self, scope: &'a thread::Scope<'a, '_>) -> Result<(), Error> { log::info!( "max {} simultaneous clients/transfers", @@ -246,14 +253,18 @@ where Ok(()) } - + /// # Errors + /// + /// Will return `Err` if the `send` returns a `SendError`. pub fn new_client(&self, client: C) -> Result<(), Error> { if let Err(e) = self.to_server.send(Some(client)) { return Err(Error::Diode(format!("failed to enqueue client: {e}"))); } Ok(()) } - + /// # Errors + /// + /// Will return `Err` if the `send` returns a `SendError`. pub fn stop(&self) -> Result<(), Error> { if let Err(e) = self.to_server.send(None) { return Err(Error::Diode(format!("failed to stop: {e}")));