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/*!
12# Trillium server adapter for tokio
13
14```rust,no_run
15# #[allow(clippy::needless_doctest_main)]
16fn main() {
17    trillium_tokio::run(|conn: trillium::Conn| async move {
18        conn.ok("hello tokio")
19    });
20}
21```
22
23```rust,no_run
24# #[allow(clippy::needless_doctest_main)]
25#[tokio::main]
26async fn main() {
27    trillium_tokio::run_async(|conn: trillium::Conn| async move {
28        conn.ok("hello tokio")
29    }).await;
30}
31```
32*/
33
34use std::future::Future;
35
36use trillium::Handler;
37
38pub use trillium_server_common::{Binding, CloneCounterObserver, Stopper};
39
40mod client;
41pub use client::ClientConfig;
42
43mod server;
44use server::Config;
45
46pub use async_compat;
47pub use tokio;
48pub use tokio_stream;
49
50mod transport;
51pub use transport::TokioTransport;
52
53/**
54# Runs a trillium handler in a sync context with default config
55
56Runs a trillium handler on the tokio runtime with
57default configuration. See [`crate::config`] for what the defaults are
58and how to override them
59
60
61This function will block the current thread until the server shuts
62down
63*/
64pub fn run(handler: impl Handler) {
65    config().run(handler)
66}
67
68/**
69# Runs a trillium handler in an async context with default config
70
71Run the provided trillium handler on an already-running tokio runtime
72with default settings. The defaults are the same as [`crate::run`]. To
73customize these settings, see [`crate::config`].
74
75This function will poll pending until the server shuts down.
76
77*/
78pub async fn run_async(handler: impl Handler) {
79    config().run_async(handler).await
80}
81
82/**
83# Configures a server before running it
84
85## Defaults
86
87The default configuration is as follows:
88
89* port: the contents of the `PORT` env var or else 8080
90* host: the contents of the `HOST` env var or else "localhost"
91* signals handling and graceful shutdown: enabled on cfg(unix) systems
92* tcp nodelay: disabled
93* tls acceptor: none
94
95## Usage
96
97```rust
98let stopper = trillium_tokio::Stopper::new();
99# stopper.stop(); // stoppping the server immediately for the test
100trillium_tokio::config()
101    .with_port(0)
102    .with_host("127.0.0.1")
103    .without_signals()
104    .with_nodelay()
105    .with_acceptor(()) // see [`trillium_rustls`] and [`trillium_native_tls`]
106    .with_stopper(stopper)
107    .run(|conn: trillium::Conn| async move {
108        conn.ok("hello tokio")
109    });
110```
111
112See [`trillium_server_common::Config`] for more details
113
114*/
115pub fn config() -> Config<()> {
116    Config::new()
117}
118
119/**
120reexport tokio runtime block_on
121*/
122pub fn block_on<Fut: Future<Output = T>, T>(future: Fut) -> T {
123    tokio::runtime::Runtime::new().unwrap().block_on(future)
124}
125
126/// spawn and detach a Future that returns ()
127pub fn spawn<Fut: Future<Output = ()> + Send + 'static>(future: Fut) {
128    tokio::task::spawn(future);
129}
trillium_tokio/lib.rs

trillium_tokio/
lib.rs
