mtcp_rs/lib.rs
1/*
2 * mtcp - TcpListener/TcpStream *with* timeout/cancellation support
3 * This is free and unencumbered software released into the public domain.
4 */
5
6//! **mtcp** provides a "blocking" implementation of `TcpListener` and
7//! `TcpStream` with proper ***timeout*** and ***cancellation*** support.
8//!
9//! [`mtcp_rs::TcpListener`](TcpListener) and [`mtcp_rs::TcpStream`](TcpStream)
10//! pretty much are drop-in replacements for
11//! [`std::net::TcpListener`](std::net::TcpListener),
12//! [`std::net::TcpStream`](std::net::TcpListener), but with an additional
13//! *timeout* parameter in the "blocking" I/O functions – including but not
14//! limited to the `accept()` function! Also, a
15//! [`mtcp_rs::TcpCanceller`](TcpCanceller) can be used to abort "pending" I/O
16//! operation immediately, e.g. from another thread or from the Ctrl+C (SIGINT)
17//! handler, so that "cleanly" shutting down your server becomes a possibility.
18//!
19//! The "blocking" I/O operations in **mtcp** are emulated via *non-blocking*
20//! operations, using the [**`mio`**](mio) library, in order to make timeouts
21//! and cancellation support possible while also providing very high
22//! performance. But, thanks to **mtcp**, you won't have to bother with `mio`
23//! events and the event polling mechanism at all. All platforms supported by
24//! `mio` are supported by **mtcp** as well.
25//!
26//! # Usage
27//!
28//! First of all, a [`mtcp_rs::TcpManager`](TcpManager) instance for the
29//! current thread must be obtained. Then a new
30//! [`mtcp_rs::TcpListener`](TcpListener) instance can be bound to a local
31//! socket. New incoming connections are returned in the form of
32//! [`mtcp_rs::TcpConnection`](TcpConnection) instances. Usually an
33//! [`mtcp_rs::TcpConnection`](TcpConnection) instance is converted into an
34//! [`mtcp_rs::TcpStream`](TcpStream) for read/write access.
35//!
36//! The function [`TcpManager::canceller()`](TcpManager) optionally provides a
37//! new [`mtcp_rs::TcpCanceller`](TcpCanceller) instance that may be used to
38//! ***cancel*** pending I/O operations. You can use, for example,
39//! [`ctrlc`](https://crates.io/crates/ctrlc) to invoke
40//! [`cancel()`](TcpCanceller::cancel()) from your Ctrl+C (SIGINT) handler.
41//!
42//! # Examples
43//!
44//! Examples be can found in the `examples` sub-directory, or on
45//! [**GitHub**](https://github.com/dEajL3kA/mtcp/tree/master/examples).
46
47mod canceller;
48mod connection;
49mod stream;
50mod manager;
51mod error;
52mod listener;
53mod utilities;
54
55pub use canceller::TcpCanceller;
56pub use connection::TcpConnection;
57pub use error::TcpError;
58pub use listener::TcpListener;
59pub use manager::TcpManager;
60pub use stream::TcpStream;