std_embedded_nal_async/
lib.rs

1//! This crate implements the [embedded-nal-async] network traits for operating systems that
2//! support the standard library's network.
3//!
4//! As of now, only UDP sockets and DNS are implemented.
5//!
6//! All implementations use `std::io::Error` as their error type.
7//!
8//! [embedded-nal-async]: https://crates.io/crates/embedded-nal-async
9//!
10//! # Caveats
11//!
12//! ## Portability
13//!
14//! The current version uses the [nix] crate to get `IP_PKTINFO` / `IPV6_PKTINFO` from received
15//! packets as the UDP trait requires. This is only portable within POSIX systems, where the
16//! [`recvmsg` call](https://www.man7.org/linux/man-pages/man3/recvmsg.3p.html) is provided. The
17//! UniquelyBound version works without that restriction, but so far there has not been a need to
18//! run this on non-POSIX systems.
19//!
20//! ## UDP uniquely bound: excessive lengths
21//!
22//! Received messages whose length exceeds the provided buffer are not yet reported correctly for
23//! UDP's uniquely bound sockets. (They work as they shoudl for the multiply bound sockets, which
24//! depend on `recvmsg`, which allows detecting the overly long messages).
25//!
26//! ## Excessive lifetimes of receive buffers
27//!
28//! As required by the [embedded_nal_async] APIs, buffers are provided through exclusive references
29//! that are pinned for th eduration of the Future. The receive functions each have only one await
30//! point, so it would suffice if the buffers were provided just for the time of the poll calls on
31//! the future (as it would be done on `nb`); it has yet to be evaluated whether (in an application
32//! that uses up the buffers before it waits again) this makes an acutal difference when running on
33//! full link time optimization.
34
35mod conversion;
36mod dns;
37mod tcp;
38mod udp;
39
40/// The operating system's network stack, implementing ``embedded_nal_async::UdpStack``.
41///
42/// The user may instantiate a stack using the `Stack::default()` function.
43///
44/// The stack can be cloned, as it is not a resource that needs any synchronization. This is not
45/// made implicit as Copy, though (although there's not technical reason not to). That is to alert
46/// users to the difficulties that'd arise when copying around a stack rather than using it through
47/// some mechanism of synchronization.
48#[derive(Clone, Default)]
49pub struct Stack;