veloren_network/
lib.rs

1#![deny(unsafe_code)]
2#![cfg_attr(test, deny(rust_2018_idioms))]
3#![cfg_attr(test, deny(warnings))]
4#![deny(clippy::clone_on_ref_ptr)]
5
6//! Crate to handle high level networking of messages with different
7//! requirements and priorities over a number of protocols
8//!
9//! To start with the `veloren_network` crate you should focus on the 3
10//! elementar structs [`Network`], [`Participant`] and [`Stream`].
11//!
12//! Say you have an application that wants to communicate with other application
13//! over a Network or on the same computer. Now each application instances the
14//! struct [`Network`] once with a new [`Pid`]. The Pid is necessary to identify
15//! other [`Networks`] over the network protocols (e.g. TCP, UDP, QUIC, MPSC)
16//!
17//! To connect to another application, you must know it's [`ConnectAddr`]. One
18//! side will call [`connect`], the other [`connected`]. If successful both
19//! applications will now get a [`Participant`].
20//!
21//! This [`Participant`] represents the connection between those 2 applications.
22//! over the respective [`ConnectAddr`] and with it the chosen network
23//! protocol. However messages can't be send directly via [`Participants`],
24//! instead you must open a [`Stream`] on it. Like above, one side has to call
25//! [`open`], the other [`opened`]. [`Streams`] can have a different priority
26//! and [`Promises`].
27//!
28//! You can now use the [`Stream`] to [`send`] and [`recv`] in both directions.
29//! You can send all kind of messages that implement [`serde`].
30//! As the receiving side needs to know the format, it sometimes is useful to
31//! always send a specific Enum and then handling it with a big `match`
32//! statement This create makes heavily use of `async`, except for [`send`]
33//! which returns always directly.
34//!
35//! For best practices see the `examples` folder of this crate containing useful
36//! code snippets, a simple client/server below. Of course due to the async
37//! nature, no strict client server separation is necessary
38//!
39//! # Examples
40//! ```rust
41//! use std::sync::Arc;
42//! use tokio::{join, runtime::Runtime, time::sleep};
43//! use veloren_network::{ConnectAddr, ListenAddr, Network, Pid, Promises};
44//!
45//! // Client
46//! async fn client(runtime: &Runtime) -> Result<(), Box<dyn std::error::Error>> {
47//!     sleep(std::time::Duration::from_secs(1)).await; // `connect` MUST be after `listen`
48//!     let client_network = Network::new(Pid::new(), runtime);
49//!     let server = client_network
50//!         .connect(ConnectAddr::Tcp("127.0.0.1:12345".parse().unwrap()))
51//!         .await?;
52//!     let mut stream = server
53//!         .open(4, Promises::ORDERED | Promises::CONSISTENCY, 0)
54//!         .await?;
55//!     stream.send("Hello World")?;
56//!     Ok(())
57//! }
58//!
59//! // Server
60//! async fn server(runtime: &Runtime) -> Result<(), Box<dyn std::error::Error>> {
61//!     let mut server_network = Network::new(Pid::new(), runtime);
62//!     server_network
63//!         .listen(ListenAddr::Tcp("127.0.0.1:12345".parse().unwrap()))
64//!         .await?;
65//!     let mut client = server_network.connected().await?;
66//!     let mut stream = client.opened().await?;
67//!     let msg: String = stream.recv().await?;
68//!     println!("Got message: {}", msg);
69//!     assert_eq!(msg, "Hello World");
70//!     Ok(())
71//! }
72//!
73//! fn main() -> Result<(), Box<dyn std::error::Error>> {
74//!     let runtime = Runtime::new().unwrap();
75//!     runtime.block_on(async {
76//!         let (result_c, result_s) = join!(client(&runtime), server(&runtime),);
77//!         result_c?;
78//!         result_s?;
79//!         Ok(())
80//!     })
81//! }
82//! ```
83//!
84//! [`Network`]: crate::api::Network
85//! [`Networks`]: crate::api::Network
86//! [`connect`]: crate::api::Network::connect
87//! [`connected`]: crate::api::Network::connected
88//! [`Participant`]: crate::api::Participant
89//! [`Participants`]: crate::api::Participant
90//! [`open`]: crate::api::Participant::open
91//! [`opened`]: crate::api::Participant::opened
92//! [`Stream`]: crate::api::Stream
93//! [`Streams`]: crate::api::Stream
94//! [`send`]: crate::api::Stream::send
95//! [`recv`]: crate::api::Stream::recv
96//! [`Pid`]: network_protocol::Pid
97//! [`ListenAddr`]: crate::api::ListenAddr
98//! [`ConnectAddr`]: crate::api::ConnectAddr
99//! [`Promises`]: network_protocol::Promises
100
101mod api;
102mod channel;
103mod message;
104mod metrics;
105mod participant;
106mod scheduler;
107mod util;
108
109pub use api::{
110    ConnectAddr, ListenAddr, Network, NetworkConnectError, NetworkError, Participant,
111    ParticipantError, ParticipantEvent, Stream, StreamError, StreamParams,
112};
113pub use message::Message;
114pub use network_protocol::{InitProtocolError, Pid, Promises};
veloren_network/lib.rs

veloren_network/
lib.rs
