neli/router/mod.rs
1//! High level API that performs sequence and PID checking as well as ACK validation.
2//!
3//! ## Workflow
4//! * [`NlRouter::send`][crate::router::synchronous::NlRouter] sends a message and
5//! does automatic seq handling.
6//! * A thread in the background receives all messages that sent to the socket in
7//! response.
8//! * Each message is sent on the channel match the sequence number to the
9//! [`NlRouterReceiverHandle`][crate::router::synchronous::NlRouterReceiverHandle] that corresponds
10//! to the request.
11//! * Errors in packet reception and parsing are broadcast to all receivers.
12//! * An [`NlRouterReceiverHandle`][crate::router::synchronous::NlRouterReceiverHandle]
13//! can be used as an iterator and will return [`None`] either when all
14//! messages corresponding to the request have been received or there is a fatal error.
15//!
16//! ## Design decisions
17//! Older users of the library might recognize some of the funtionality in
18//! [`NlRouter`][crate::router::synchronous::NlRouter] as code that previously was
19//! associated with [`NlSocketHandle`][crate::socket::synchronous::NlSocketHandle].
20//! The reason for this migration is primarily due to some deficiencies found in the
21//! previous implementation.
22//! [`NlSocketHandle`][crate::socket::synchronous::NlSocketHandle]
23//! relied heavily on a `.send()`/`.recv()` workflow. This meant that, while it
24//! was designed to address ACK handling and receiving all responses associated
25//! with a given request, the implementation actually was unable to handle two
26//! separate responses corresponding to two seaparate requests interleaved with each
27//! other. Effectively, this meant that the socket handle had no awareness of multiple
28//! requests being sent before all data was read from the socket and would result
29//! in parsing errors if used in this way.
30//!
31//! [`NlRouter`][crate::router::synchronous::NlRouter] aims to address this by
32//! associating all messages received by the socket with a request or multicast
33//! group so that messages can be interleaved and still processed in the correct
34//! order by the handle associated with the request that generated it.
35//!
36//! ## Features
37//! The `async` feature exposed by `cargo` allows the socket to use
38//! Rust's [tokio](https://tokio.rs) for async IO.
39
40/// Asynchronous packet routing functionality.
41#[cfg(feature = "async")]
42pub mod asynchronous;
43/// Synchronous packet routing functionality.
44#[cfg(feature = "sync")]
45pub mod synchronous;