safina/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
//! [![crates.io version](https://img.shields.io/crates/v/safina.svg)](https://crates.io/crates/safina)
//! [![license: Apache 2.0](https://gitlab.com/leonhard-llc/safina-rs/-/raw/main/license-apache-2.0.svg)](http://www.apache.org/licenses/LICENSE-2.0)
//! [![unsafe forbidden](https://gitlab.com/leonhard-llc/safina-rs/-/raw/main/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
//! [![pipeline status](https://gitlab.com/leonhard-llc/safina-rs/badges/main/pipeline.svg)](https://gitlab.com/leonhard-llc/safina-rs/-/pipelines)
//!
//! A safe Rust async runtime.
//!
//! # Features
//! - `forbid(unsafe_code)`
//! - Depends only on `std`
//! - Good test coverage (>95%)
//!
//! # Limitations
//! - No `fs` module yet.
//!   [`async-fs`](https://crates.io/crates/async-fs) is a fast async networking library
//!   that works well with Safina.  It contains some unsafe code.
//! - `net` module has poor performance.
//!   [`async-net`](https://crates.io/crates/async-net) is a fast async networking library
//!   that works well with Safina.  It contains some unsafe code.
//! - Not optimized
//!
//! # Examples
//! ```rust
//! # fn f() {
//! let executor = safina::executor::Executor::default();
//! let (sender, receiver) = std::sync::mpsc::channel();
//! executor.spawn(async move {
//!     sender.send(()).unwrap();
//! });
//! receiver.recv().unwrap();
//! # }
//! ```
//!
//! ```rust
//! # async fn prepare_request() -> Result<(), std::io::Error> { Ok(()) }
//! # async fn execute_request() -> Result<(), std::io::Error> { Ok(()) }
//! # fn f() -> Result<(), std::io::Error> {
//! let result = safina::executor::block_on(async {
//!     prepare_request().await?;
//!     execute_request().await
//! })?;
//! # Ok(())
//! # }
//! ```
//!
//! # Alternatives
//! - [`smol`](https://crates.io/crates/smol)
//!   - Popular
//!   - Contains some `unsafe` code
//! - [`async-std`](https://crates.io/crates/async-std)
//!   - Very popular
//!   - Contains generous amounts of `unsafe` code
//! - [`futures`](https://crates.io/crates/futures)
//!   - Very popular
//!   - Contains generous amounts of `unsafe` code
//! - [`tokio`](https://crates.io/crates/tokio)
//!   - Very popular
//!   - Fast
//!   - Internally extremely complicated
//!   - Full of `unsafe` code
//! - [`bastion`](https://crates.io/crates/bastion)
//!   - Generous amounts of `unsafe` code
//! - [`nostd_async`](https://crates.io/crates/nostd_async)
//!
//! # Cargo Geiger Safety Report
//! # Changelog
//! <details>
//! <summary>Changelog</summary>
//! - v0.4.0 2024-10-26 - Merge crates into this crate
//!    - [`safina-async-test`](https://crates.io/crates/safina-async-test)
//!    - [`safina-executor`](https://crates.io/crates/safina-executor)
//!    - [`safina-net`](https://crates.io/crates/safina-net)
//!    - [`safina-select`](https://crates.io/crates/safina-select)
//!    - [`safina-sync`](https://crates.io/crates/safina-sync)
//!    - [`safina-threadpool`](https://crates.io/crates/safina-threadpool)
//!    - [`safina-timer`](https://crates.io/crates/safina-timer)
//! - v0.3.3 - Update docs.
//! - v0.3.2 - Add `threadpool` module.
//! - v0.3.1
//!   - Add `sync_channel` and `SyncSender`.
//!   - Add `Receiver::async_recv` to let users await without writing ugly `(&mut receiver).await`.
//!   - Remove `Receiver::blocking` and add `try_recv`, `recv`, etc.
//! - v0.3.0
//!   - Move structs into sub-modules.
//!   - Replace `Promise` with `oneshot`, `OneSender`, and `Receiver` that supports async and blocking reads.
//!   - `schedule_blocking` to return new `sync::Receiver`.
//! - v0.2.1 - Update docs.
//! - v0.2.0
//!   - `Executor::new` and `Executor::with_name` to return `Result`.
//!   - `ThreadPool::new` to return `Result`.
//!   - `ThreadPool::try_schedule` to return an error when it fails to restart panicked threads.
//!   - `ThreadPool::schedule` to handle failure starting replacement threads.
//! - v0.1.10 - `block_on` functions to take futures that are not `Send`.
//! - v0.1.9 - Use `once_cell` by default.
//! - v0.1.8 - Support stable with rust 1.51 and `once_cell`.
//! - v0.1.7 - Add [`safina-net`](https://crates.io/crates/safina-net)
//! - v0.1.6 - Use [`safina-executor`](https://crates.io/crates/safina-executor) v0.1.3 API
//! - v0.1.5 - Add [`safina::sync::Mutex`](https://docs.rs/safina-sync/latest/safina::sync/struct.Mutex.html)
//! - v0.1.4 - Upgrade to new safina-executor version which removes need for `Box::pin`.
//! - v0.1.3 - Update docs
//! - v0.1.2 - Renamed `safina` crate to `safina-executor`.
//!   Added new `safina` crate with re-exports, examples, and integration tests.
//! - v0.1.1 - Add badges to readme
//! - v0.1.0 - First published version
//!
//! </details>
//!
//! # TO DO
//! - Add `init` function that makes an executor and starts the timer thread.
//! - Add an `#[async_main]` macro
#![forbid(unsafe_code)]

#[cfg(feature = "executor")]
pub mod executor;
#[cfg(feature = "net")]
pub mod net;
#[cfg(feature = "select")]
pub mod select;
#[cfg(feature = "sync")]
pub mod sync;
#[cfg(feature = "threadpool")]
pub mod threadpool;
#[cfg(feature = "timer")]
pub mod timer;

#[cfg(feature = "async_test")]
pub use safina_macros::async_test;