https://github.com/rust-embedded/nb

Minimal and reusable non-blocking I/O layer
https://github.com/rust-embedded/nb

Last synced: 3 months ago
JSON representation

Minimal and reusable non-blocking I/O layer

• Host: GitHub
• URL: https://github.com/rust-embedded/nb
• Owner: rust-embedded
• License: apache-2.0
• Created: 2017-06-08T03:49:59.000Z (about 8 years ago)
• Default Branch: master
• Last Pushed: 2024-01-16T09:37:10.000Z (over 1 year ago)
• Last Synced: 2025-03-28T12:08:58.102Z (3 months ago)
• Language: Rust
• Size: 589 KB
• Stars: 94
• Watchers: 12
• Forks: 15
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE-APACHE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

        
[![crates.io](https://img.shields.io/crates/d/nb.svg)](https://crates.io/crates/nb)

[![crates.io](https://img.shields.io/crates/v/nb.svg)](https://crates.io/crates/nb)

[![Documentation](https://docs.rs/nb/badge.svg)](https://docs.rs/nb)

![Minimum Supported Rust Version](https://img.shields.io/badge/rustc-1.62+-blue.svg)

# `nb`

> Minimal and reusable non-blocking I/O layer

This project is developed and maintained by the [HAL team][team].

## [Documentation](https://docs.rs/nb)

The ultimate goal of this crate is *code reuse*. With this crate you can

write *core* I/O APIs that can then be adapted to operate in either blocking

or non-blocking manner. Furthermore those APIs are not tied to a particular

asynchronous model and can be adapted to work with the `futures` model or

with the `async` / `await` model.

### Core idea

The [`WouldBlock`](enum.Error.html) error variant signals that the operation

can't be completed *right now* and would need to block to complete.

[`WouldBlock`](enum.Error.html) is a special error in the sense that it's not

*fatal*; the operation can still be completed by retrying again later.

[`nb::Result`](type.Result.html) is based on the API of

[`std::io::Result`](https://doc.rust-lang.org/std/io/type.Result.html),

which has a `WouldBlock` variant in its

[`ErrorKind`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html).

We can map [`WouldBlock`](enum.Error.html) to different blocking and

non-blocking models:

- In blocking mode, [`WouldBlock`](enum.Error.html) means try again right

  now, i.e. busy waiting.

- In `async` mode, [`WouldBlock`](enum.Error.html) means

  [`Poll::Pending`](https://doc.rust-lang.org/core/task/enum.Poll.html#variant.Pending).

## Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on stable Rust 1.62 and up. It *might*

compile with older versions but that may change in any new patch release.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or

  )

- MIT license ([LICENSE-MIT](LICENSE-MIT) or )

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted

for inclusion in the work by you, as defined in the Apache-2.0 license, shall be

dual licensed as above, without any additional terms or conditions.

## Code of Conduct

Contribution to this crate is organized under the terms of the [Rust Code of

Conduct][CoC], the maintainer of this crate, the [HAL team][team], promises

to intervene to uphold that code of conduct.

[CoC]: CODE_OF_CONDUCT.md

[team]: https://github.com/rust-embedded/wg#the-hal-team