doc structure

veilid-tools/src/assembly_buffer.rs

@@ -1,3 +1,7 @@
+//! Packet reassembly and fragmentation handler
+//!
+//! * [AssemblyBuffer] handles both the sender and received end of fragmentation and reassembly.
+
 use super::*;
 use range_set_blaze::RangeSetBlaze;
 use std::io::{Error, ErrorKind};
@@ -12,7 +16,12 @@ const MAX_LEN: usize = LengthType::MAX as usize;
 
 // XXX: keep statistics on all drops and why we dropped them
 // XXX: move to config eventually?
+
+/// The hard-coded maximum fragment size used by AssemblyBuffer
+///
+/// Eventually this should parameterized and made configurable.
 pub const FRAGMENT_LEN: usize = 1280 - HEADER_LEN;
+
 const MAX_CONCURRENT_HOSTS: usize = 256;
 const MAX_ASSEMBLIES_PER_HOST: usize = 256;
 const MAX_BUFFER_PER_HOST: usize = 256 * 1024;
@@ -202,8 +211,23 @@ struct AssemblyBufferUnlockedInner {
 }
 
 /// Packet reassembly and fragmentation handler
-/// No retry, no acknowledgment, no flow control
+///
-/// Just trying to survive lower path MTU for larger messages
+/// Used to provide, for raw unordered protocols such as UDP, a means to achieve:
+///
+/// * Fragmentation of packets to ensure they are smaller than a common MTU
+/// * Reassembly of fragments upon receipt accounting for:
+///   * duplication
+///   * drops
+///   * overlaops
+///     
+/// AssemblyBuffer does not try to replicate TCP or other highly reliable protocols. Here are some
+/// of the design limitations to be aware of when using AssemblyBuffer:
+///
+/// * No packet acknowledgment. The sender does not know if a packet was received.
+/// * No flow control. If there are buffering problems or drops, the sender and receiver have no protocol to address this.
+/// * No retries or retransmission.
+/// * No sequencing of packets. Packets may still be delivered to the application out of order, but this guarantees that only whole packets will be delivered if all of their fragments are received.
+
 #[derive(Clone)]
 pub struct AssemblyBuffer {
     inner: Arc<Mutex<AssemblyBufferInner>>,

veilid-tools/src/lib.rs

@@ -1,32 +1,41 @@
-// mod bump_port;
+//! A collection of baseline tools for Rust development use by Veilid and Veilid-enabled Rust applications
-mod assembly_buffer;
+//!
-mod async_peek_stream;
+//! These are used by `veilid-core`, `veilid-server`, `veilid-cli` and may be used by any other applications
-mod async_tag_lock;
+//! that link in `veilid-core` if a common baseline of functionality is desired. Extending this crate with new
-mod clone_stream;
+//! utility functions is encouraged rather than adding 'common' functionality to `veilid-core`, allowing it to
-mod eventual;
+//! remain free of boilerplate and utility classes that could be reused elsewhere.
-mod eventual_base;
+//!
-mod eventual_value;
+//! Everything added to this crate must be extensively unit-tested.
-mod eventual_value_clone;
+
-mod interval;
+// pub mod bump_port;
-mod ip_addr_port;
+pub mod assembly_buffer;
-mod ip_extra;
+pub mod async_peek_stream;
-mod log_thru;
+pub mod async_tag_lock;
-mod must_join_handle;
+pub mod clone_stream;
-mod must_join_single_future;
+pub mod eventual;
-mod mutable_future;
+pub mod eventual_base;
-mod network_result;
+pub mod eventual_value;
-mod random;
+pub mod eventual_value_clone;
-mod single_shot_eventual;
+pub mod interval;
-mod sleep;
+pub mod ip_addr_port;
-mod spawn;
+pub mod ip_extra;
-mod split_url;
+pub mod log_thru;
-mod tick_task;
+pub mod must_join_handle;
-mod timeout;
+pub mod must_join_single_future;
-mod timeout_or;
+pub mod mutable_future;
-mod timestamp;
+pub mod network_result;
-mod tools;
+pub mod random;
+pub mod single_shot_eventual;
+pub mod sleep;
+pub mod spawn;
+pub mod split_url;
+pub mod tick_task;
+pub mod timeout;
+pub mod timeout_or;
+pub mod timestamp;
+pub mod tools;
 #[cfg(target_arch = "wasm32")]
-mod wasm;
+pub mod wasm;
 
 pub type PinBox<T> = Pin<Box<T>>;
 pub type PinBoxFuture<T> = PinBox<dyn Future<Output = T> + 'static>;
@@ -34,51 +43,88 @@ pub type PinBoxFutureLifetime<'a, T> = PinBox<dyn Future<Output = T> + 'a>;
 pub type SendPinBoxFuture<T> = PinBox<dyn Future<Output = T> + Send + 'static>;
 pub type SendPinBoxFutureLifetime<'a, T> = PinBox<dyn Future<Output = T> + Send + 'a>;
 
+#[doc(no_inline)]
 pub use std::borrow::{Cow, ToOwned};
+#[doc(no_inline)]
 pub use std::boxed::Box;
+#[doc(no_inline)]
 pub use std::cell::RefCell;
+#[doc(no_inline)]
 pub use std::cmp;
+#[doc(no_inline)]
 pub use std::collections::btree_map::BTreeMap;
+#[doc(no_inline)]
 pub use std::collections::btree_set::BTreeSet;
+#[doc(no_inline)]
 pub use std::collections::hash_map::HashMap;
+#[doc(no_inline)]
 pub use std::collections::hash_set::HashSet;
+#[doc(no_inline)]
 pub use std::collections::LinkedList;
+#[doc(no_inline)]
 pub use std::collections::VecDeque;
+#[doc(no_inline)]
 pub use std::convert::{TryFrom, TryInto};
+#[doc(no_inline)]
 pub use std::fmt;
+#[doc(no_inline)]
 pub use std::future::Future;
+#[doc(no_inline)]
 pub use std::mem;
+#[doc(no_inline)]
 pub use std::net::{
     IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs,
 };
+#[doc(no_inline)]
 pub use std::ops::{Fn, FnMut, FnOnce};
+#[doc(no_inline)]
 pub use std::pin::Pin;
+#[doc(no_inline)]
 pub use std::rc::Rc;
+#[doc(no_inline)]
 pub use std::str::FromStr;
+#[doc(no_inline)]
 pub use std::string::{String, ToString};
+#[doc(no_inline)]
 pub use std::sync::atomic::{AtomicBool, Ordering};
+#[doc(no_inline)]
 pub use std::sync::{Arc, Weak};
+#[doc(no_inline)]
 pub use std::task;
+#[doc(no_inline)]
 pub use std::time::Duration;
+#[doc(no_inline)]
 pub use std::vec::Vec;
 
 cfg_if! {
     if #[cfg(target_arch = "wasm32")] {
+        #[doc(no_inline)]
         pub use async_lock::Mutex as AsyncMutex;
+        #[doc(no_inline)]
         pub use async_lock::MutexGuard as AsyncMutexGuard;
+        #[doc(no_inline)]
         pub use async_lock::MutexGuardArc as AsyncMutexGuardArc;
+        #[doc(no_inline)]
         pub use async_executors::JoinHandle as LowLevelJoinHandle;
     } else {
         cfg_if! {
             if #[cfg(feature="rt-async-std")] {
+                #[doc(no_inline)]
                 pub use async_std::sync::Mutex as AsyncMutex;
+                #[doc(no_inline)]
                 pub use async_std::sync::MutexGuard as AsyncMutexGuard;
+                #[doc(no_inline)]
                 pub use async_std::sync::MutexGuardArc as AsyncMutexGuardArc;
+                #[doc(no_inline)]
                 pub use async_std::task::JoinHandle as LowLevelJoinHandle;
             } else if #[cfg(feature="rt-tokio")] {
+                #[doc(no_inline)]
                 pub use tokio::sync::Mutex as AsyncMutex;
+                #[doc(no_inline)]
                 pub use tokio::sync::MutexGuard as AsyncMutexGuard;
+                #[doc(no_inline)]
                 pub use tokio::sync::OwnedMutexGuard as AsyncMutexGuardArc;
+                #[doc(no_inline)]
                 pub use tokio::task::JoinHandle as LowLevelJoinHandle;
             } else {
                 #[compile_error("must use an executor")]
@@ -88,31 +134,57 @@ cfg_if! {
 }
 
 // pub use bump_port::*;
+#[doc(inline)]
 pub use assembly_buffer::*;
+#[doc(inline)]
 pub use async_peek_stream::*;
+#[doc(inline)]
 pub use async_tag_lock::*;
+#[doc(inline)]
 pub use clone_stream::*;
+#[doc(inline)]
 pub use eventual::*;
+#[doc(inline)]
 pub use eventual_base::{EventualCommon, EventualResolvedFuture};
+#[doc(inline)]
 pub use eventual_value::*;
+#[doc(inline)]
 pub use eventual_value_clone::*;
+#[doc(inline)]
 pub use interval::*;
+#[doc(inline)]
 pub use ip_addr_port::*;
+#[doc(inline)]
 pub use ip_extra::*;
+#[doc(inline)]
 pub use log_thru::*;
+#[doc(inline)]
 pub use must_join_handle::*;
+#[doc(inline)]
 pub use must_join_single_future::*;
+#[doc(inline)]
 pub use mutable_future::*;
+#[doc(inline)]
 pub use network_result::*;
+#[doc(inline)]
 pub use random::*;
+#[doc(inline)]
 pub use single_shot_eventual::*;
+#[doc(inline)]
 pub use sleep::*;
+#[doc(inline)]
 pub use spawn::*;
+#[doc(inline)]
 pub use split_url::*;
+#[doc(inline)]
 pub use tick_task::*;
+#[doc(inline)]
 pub use timeout::*;
+#[doc(inline)]
 pub use timeout_or::*;
+#[doc(inline)]
 pub use timestamp::*;
+#[doc(inline)]
 pub use tools::*;
 
 #[cfg(target_arch = "wasm32")]