trillium_tokio/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(
3    clippy::dbg_macro,
4    missing_copy_implementations,
5    rustdoc::missing_crate_level_docs,
6    missing_debug_implementations,
7    missing_docs,
8    nonstandard_style,
9    unused_qualifications
10)]
11//! # Trillium server adapter for tokio
12//!
13//! ```rust,no_run
14//! # #[allow(clippy::needless_doctest_main)]
15//! fn main() {
16//!     trillium_tokio::run(|conn: trillium::Conn| async move { conn.ok("hello tokio") });
17//! }
18//! ```
19//!
20//! ```rust,no_run
21//! # #[allow(clippy::needless_doctest_main)]
22//! #[tokio::main]
23//! async fn main() {
24//!     trillium_tokio::run_async(|conn: trillium::Conn| async move { conn.ok("hello tokio") })
25//!         .await;
26//! }
27//! ```
28
29#[cfg(test)]
30#[doc = include_str!("../README.md")]
31mod readme {}
32
33use trillium::Handler;
34pub use trillium_server_common::{Binding, Swansong};
35
36mod client;
37pub use client::ClientConfig;
38
39mod server;
40pub use async_compat;
41use server::Config;
42pub use tokio;
43pub use tokio_stream;
44
45mod transport;
46pub use transport::TokioTransport;
47
48/// # Runs a trillium handler in a sync context with default config
49///
50/// Runs a trillium handler on the tokio runtime with
51/// default configuration. See [`crate::config`] for what the defaults are
52/// and how to override them
53///
54///
55/// This function will block the current thread until the server shuts
56/// down
57pub fn run(handler: impl Handler) {
58    config().run(handler)
59}
60
61/// # Runs a trillium handler in an async context with default config
62///
63/// Run the provided trillium handler on an already-running tokio runtime
64/// with default settings. The defaults are the same as [`crate::run`]. To
65/// customize these settings, see [`crate::config`].
66///
67/// This function will poll pending until the server shuts down.
68pub async fn run_async(handler: impl Handler) {
69    config().run_async(handler).await
70}
71
72/// # Configures a server before running it
73///
74/// ## Defaults
75///
76/// The default configuration is as follows:
77///
78/// port: the contents of the `PORT` env var or else 8080
79/// host: the contents of the `HOST` env var or else "localhost"
80/// signals handling and graceful shutdown: enabled on cfg(unix) systems
81/// tcp nodelay: disabled
82/// tls acceptor: none
83///
84/// ## Usage
85///
86/// ```rust
87/// let swansong = trillium_tokio::Swansong::new();
88/// # swansong.shut_down(); // stoppping the server immediately for the test
89/// trillium_tokio::config()
90///     .with_port(0)
91///     .with_host("127.0.0.1")
92///     .without_signals()
93///     .with_nodelay()
94///     .with_acceptor(()) // see [`trillium_rustls`] and [`trillium_native_tls`]
95///     .with_swansong(swansong)
96///     .run(|conn: trillium::Conn| async move { conn.ok("hello tokio") });
97/// ```
98///
99/// See [`trillium_server_common::Config`] for more details
100pub fn config() -> Config<()> {
101    Config::new()
102}
103
104mod runtime;
105pub use runtime::TokioRuntime;
106
107mod udp;
108pub use udp::TokioUdpSocket;
trillium_tokio/lib.rs

trillium_tokio/
lib.rs
