Skip to content

Commit 7ce469c

Browse files
chore: update library doc home page
1 parent 1f3fa51 commit 7ce469c

File tree

1 file changed

+44
-60
lines changed

1 file changed

+44
-60
lines changed

mqrstt/src/lib.rs

+44-60
Original file line numberDiff line numberDiff line change
@@ -4,62 +4,57 @@
44
//! For an async approach the stream has to implement the `AsyncRead` and `AsyncWrite` traits.
55
//! That is [`::tokio::io::AsyncRead`] and [`::tokio::io::AsyncWrite`] for tokio and [`::smol::io::AsyncRead`] and [`::smol::io::AsyncWrite`] for smol.
66
//!
7+
//!
8+
//!
79
//! Features:
810
//! ----------------------------
9-
//! - MQTT v5
10-
//! - Runtime agnostic (Smol, Tokio)
11-
//! - Packets are acknoledged after handler has processed them
12-
//! - Runs on just a stream so you can use all TCP backends
13-
//! - Lean
14-
//! - Keep alive depends on actual communication
11+
//! - MQTT v5
12+
//! - Runtime agnostic (Smol, Tokio)
13+
//! - Sync
14+
//! - TLS/TCP
15+
//! - Lean
16+
//! - Keep alive depends on actual communication
17+
//! - This tokio implemention has been fuzzed using cargo-fuzz!
18+
//!
19+
//! To do:
20+
//! ----------------------------
21+
//! - Even More testing
22+
//! - Add TLS examples to repository
1523
//!
16-
//! To do
24+
//! Minimum Supported Rust Version (MSRV):
1725
//! ----------------------------
18-
//! - Even More testing
26+
//! From 0.3 the tokio and smol variants will require MSRV: 1.75 due to async fn in trait feature.
1927
//!
2028
//! Notes:
2129
//! ----------------------------
22-
//! - Handlers only get incoming packets
30+
//! - Your handler should not wait too long
2331
//! - Create a new connection when an error or disconnect is encountered
32+
//! - Handlers only get incoming packets
2433
//!
2534
//! Smol example:
2635
//! ----------------------------
2736
//! ```rust
28-
//! use mqrstt::{
29-
//! MqttClient,
30-
//! example_handlers::NOP,
31-
//! ConnectOptions,
32-
//! packets::{self, Packet},
33-
//! AsyncEventHandler,
34-
//! NetworkStatus,
35-
//! NetworkBuilder,
36-
//! };
37+
//! use mqrstt::{example_handlers::NOP, NetworkBuilder, NetworkStatus};
3738
//!
3839
//! smol::block_on(async {
3940
//! // Construct a no op handler
40-
//! let mut nop = NOP{};
41+
//! let mut nop = NOP {};
4142
//!
4243
//! // In normal operations you would want to loop this connection
4344
//! // To reconnect after a disconnect or error
44-
//! let (mut network, client) = NetworkBuilder
45-
//! ::new_from_client_id("mqrsttSmolExample")
46-
//! .smol_network();
47-
//! let stream = smol::net::TcpStream::connect(("broker.emqx.io", 1883))
48-
//! .await
49-
//! .unwrap();
45+
//! let (mut network, client) = NetworkBuilder::new_from_client_id("mqrsttSmolExample").smol_network();
46+
//! let stream = smol::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap();
5047
//! network.connect(stream, &mut nop).await.unwrap();
51-
//!
48+
//!
5249
//! // This subscribe is only processed when we run the network
5350
//! client.subscribe("mqrstt").await.unwrap();
5451
//!
55-
//! let (n, t) = futures::join!(
56-
//! network.run(&mut nop),
57-
//! async {
58-
//! smol::Timer::after(std::time::Duration::from_secs(30)).await;
59-
//! client.disconnect().await.unwrap();
60-
//! }
61-
//! );
62-
//! assert!(n.is_ok());
52+
//! let (result, _) = futures::join!(network.run(&mut nop), async {
53+
//! smol::Timer::after(std::time::Duration::from_secs(30)).await;
54+
//! client.disconnect().await.unwrap();
55+
//! });
56+
//! assert!(result.is_ok());
57+
//! assert_eq!(result.unwrap(), NetworkStatus::OutgoingDisconnect);
6358
//! });
6459
//! ```
6560
//!
@@ -68,42 +63,31 @@
6863
//! ----------------------------
6964
//! ```rust
7065
//! use mqrstt::{
71-
//! MqttClient,
7266
//! example_handlers::NOP,
73-
//! ConnectOptions,
74-
//! packets::{self, Packet},
75-
//! AsyncEventHandler,
76-
//! NetworkStatus,
77-
//! NetworkBuilder,
67+
//! NetworkBuilder, NetworkStatus,
7868
//! };
69+
//!
7970
//! use tokio::time::Duration;
8071
//!
8172
//! #[tokio::main]
8273
//! async fn main() {
83-
//! let (mut network, client) = NetworkBuilder
84-
//! ::new_from_client_id("TokioTcpPingPongExample")
85-
//! .tokio_network();
86-
//!
74+
//! let (mut network, client) = NetworkBuilder::new_from_client_id("TokioTcpPingPongExample").tokio_network();
8775
//! // Construct a no op handler
88-
//! let mut nop = NOP{};
89-
//!
76+
//! let mut nop = NOP {};
9077
//! // In normal operations you would want to loop this connection
91-
//! // To reconnect after a disconnect or error
92-
//! let stream = tokio::net::TcpStream::connect(("broker.emqx.io", 1883))
93-
//! .await
94-
//! .unwrap();
78+
//! // To reconnect after a disconnect or error
79+
//! let stream = tokio::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap();
9580
//! network.connect(stream, &mut nop).await.unwrap();
96-
//!
81+
//!
9782
//! client.subscribe("mqrstt").await.unwrap();
98-
//!
99-
//! let (n, _) = futures::join!(
100-
//! network.run(&mut nop),
101-
//! async {
102-
//! tokio::time::sleep(Duration::from_secs(30)).await;
103-
//! client.disconnect().await.unwrap();
104-
//! }
105-
//! );
106-
//! assert!(n.is_ok());
83+
//! // Run the network
84+
//! let network_handle = tokio::spawn(async move { network.run(&mut nop).await });
85+
//!
86+
//! tokio::time::sleep(Duration::from_secs(30)).await;
87+
//! client.disconnect().await.unwrap();
88+
//! let result = network_handle.await;
89+
//! assert!(result.is_ok());
90+
//! assert_eq!(result.unwrap().unwrap(), NetworkStatus::OutgoingDisconnect);
10791
//! }
10892
//! ```
10993

0 commit comments

Comments
 (0)