WIP soundness 2

README.md

@@ -10,10 +10,10 @@
 [codecov]: https://codecov.io/gh/memflow/mfio/branch/main/graph/badge.svg?token=IJ1K4QPAIM
 [codecov-link]: https://codecov.io/gh/memflow/mfio
 
-## Async completion I/O with non-sequential results
+## Async completion I/O research with non-sequential results
 
-mfio is memflow's async completion based I/O base. It aims to make the following aspects of an
-I/O chain as simple as possible:
+mfio is memflow's research async completion based I/O base. It aims to make the following aspects
+of an I/O chain as simple as possible:
 
 1. Async
 2. Automatic batching (vectoring)

mfio/src/lib.rs

@@ -1,9 +1,9 @@
 //! # mfio
 //!
-//! ## Async completion I/O with non-sequential results
+//! ## Research async completion I/O with non-sequential results
 //!
-//! mfio is memflow's async completion based I/O base. It aims to make the following aspects of an
-//! I/O chain as simple as possible:
+//! mfio is memflow's research async completion based I/O base. It aims to make the following
+//! aspects of an I/O chain as simple as possible:
 //!
 //! 1. Async
 //! 2. Automatic batching (vectoring)
@@ -23,6 +23,12 @@
 //! works really well with sparse files, albeit differs from the typical "stop as soon as an error
 //! occurs" model.
 //!
+//! Lack of color is not true sync/async mix, instead, mfio is designed to expose minimal set of
+//! data for invoking a built-in runtime, with handles of daisy chaining mfio on top of another
+//! runtime. The end result is that mfio is able to provide sync wrappers that efficiently poll
+//! async operations to completion, while staying runtime agnostic. We found that a single (unix)
+//! file descriptor or (windows) handle is sufficient to connect multiple async runtimes together.
+//!
 //! ### Examples
 //!
 //! Read primitive values:
@@ -132,8 +138,16 @@
 //!
 //! ## Safety
 //!
-//! mfio can invoke UB in safe code if `mem::forget` is run on a packet stream and data sent to the
-//! stream gets reused.
+//! By default mfio is conservative and does not enable invoking undefined behavior. However, with
+//! a custom opt-in config switch, enabled by passing `--cfg mfio_assume_linear_types` to the rust
+//! compiler, mfio is able to provide significant performance improvements, at the cost of
+//! potential for invoking UB in safe code.
+//!
+//! With `mfio_assume_linear_types` config enabled, mfio wrappers will prefer storing data on the
+//! stack, and if a future waiting for I/O operations to complete is cancelled, a `panic!` may get
+//! triggered. Moreover, if a future waiting for I/O operations to complete gets forgotten using
+//! `mem::forget`, undefined behavior may be invoked, because use-after-(stack)-free safeguards are
+//! discarded.
 //!
 //! ### Safety examples
 //!
@@ -252,8 +266,8 @@ pub mod heap;
 pub(crate) mod multistack;
 pub mod packet;
 mod poller;
-//pub mod stdeq;
-//pub mod traits;
+pub mod stdeq;
+pub mod traits;
 pub mod util;
 
 pub use tarc;