async_nng/lib.rs
1//! # About
2//!
3//! `async-nng` is a small wrapper that uses the
4//! [`async-channel`](https://docs.rs/async-channel/latest/async_channel/) crate alongside the
5//! [`nng`](https://docs.rs/nng/latest/nng/) crate to provide types that provide async-await
6//! semantics around send and receive operations on an NNG socket.
7//!
8//! The futures that are constructed by the wrapper types in this crate directly utilize the
9//! [`nng::Aio`](https://docs.rs/nng/latest/nng/struct.Aio.html) framework, and do not use any
10//! `spawn_blocking`, `unblock`, or send any data to a backing threadpool in order to work. This
11//! makes it extremely useful to use in scenarios where the
12//! [`blocking`](https://docs.rs/blocking/latest/blocking/) crate or the `tokio` equivalent
13//! (`spawn_blocking`) are undesirable.
14//!
15//! # Installing
16//!
17//! ```bash
18//! $ cargo add async-nng
19//! ```
20//!
21//! # Runtime Selection
22//!
23//! This crate should work with any of `tokio`, `async-std`, or `smol`. The tests in this crate use
24//! `smol` purely to save on the number of dev-dependencies, but there are no types used within
25//! this crate itself that rely on spawning tasks or any executor-specific API.
26//!
27//! # `AsyncContext` and `AsyncSocket`
28//!
29//! The two primary types provided by this crate are `AsyncContext` and `AsyncSocket`. In almost
30//! all instances, one should prefer contexts to sockets when writing asynchronous and concurrent
31//! programs. See the documentation for [`AsyncContext`] for more information.
32//!
33//! [`AsyncSocket`] is provided as well for those using raw-mode sockets or who otherwise cannot
34//! take advantage of contexts. Unlike contexts which borrow the underlying [`nng::Socket`],
35//! `AsyncSocket` itself is an owning type and owns the socket. An [`AsyncSocket::into_inner`] is
36//! provided so that the original socket type can be recovered if there is an error or some other
37//! reason to get access to the underlying socket.
38//!
39//! # Acknowledgements
40//!
41//! Thanks to `@neachdainn` in the NNG discord (and maintainer of the `nng` crate) for helping me
42//! in constructing the MVP for async-await semantics wrapping the `nng` crate.
43
44mod cancel_guard;
45mod context;
46mod socket;
47
48pub use context::AsyncContext;
49pub use socket::AsyncSocket;