smol-rs
/
polling
mirror of https://github.com/smol-rs/polling
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
polling/README.md

74 lines
2.5 KiB
Markdown
Raw Normal View History

Initial commit
2020-08-06 13:02:59 +00:00
# polling
Update URLs
2020-12-26 14:47:13 +00:00
[![Build](https://github.com/smol-rs/polling/workflows/Build%20and%20test/badge.svg)](
https://github.com/smol-rs/polling/actions)
Update license badge to match Cargo.toml
2021-02-14 04:36:54 +00:00
[![License](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](
Update URLs
2020-12-26 14:47:13 +00:00
https://github.com/smol-rs/polling)
Initial commit
2020-08-06 13:02:59 +00:00
[![Cargo](https://img.shields.io/crates/v/polling.svg)](
https://crates.io/crates/polling)
[![Documentation](https://docs.rs/polling/badge.svg)](
https://docs.rs/polling)
m(windows): Reimplement Wepoll in Rust (#88) Reimplements the C-based wepoll backend in Rust, using some handwritten code. This PR also implements bindings to the I/O Completion Ports and \Device\Afd APIs. For more information on the latter, see my blog post on the subject: https://notgull.github.io/device-afd/ Note that the IOCP API is wrapped using a `Pin`-oriented "CompletionHandle" system that is relatively brittle. This should be replaced with a better model when one becomes available.
2023-03-06 00:25:25 +00:00
Portable interface to epoll, kqueue, event ports, and IOCP.
Initial commit
2020-08-06 13:02:59 +00:00
Supported platforms:
Add event ports for illumos
2020-08-06 20:28:38 +00:00
- [epoll](https://en.wikipedia.org/wiki/Epoll): Linux, Android
Support tvOS and watchOS (#60)
2022-12-20 03:54:45 +00:00
- [kqueue](https://en.wikipedia.org/wiki/Kqueue): macOS, iOS, tvOS, watchOS, FreeBSD, NetBSD, OpenBSD,
Initial commit
2020-08-06 13:02:59 +00:00
DragonFly BSD
Add event ports for illumos
2020-08-06 20:28:38 +00:00
- [event ports](https://illumos.org/man/port_create): illumos, Solaris
Document `poll` support in README
2021-09-04 17:00:25 +00:00
- [poll](https://en.wikipedia.org/wiki/Poll_(Unix)): VxWorks, Fuchsia, other Unix systems
m(windows): Reimplement Wepoll in Rust (#88) Reimplements the C-based wepoll backend in Rust, using some handwritten code. This PR also implements bindings to the I/O Completion Ports and \Device\Afd APIs. For more information on the latter, see my blog post on the subject: https://notgull.github.io/device-afd/ Note that the IOCP API is wrapped using a `Pin`-oriented "CompletionHandle" system that is relatively brittle. This should be replaced with a better model when one becomes available.
2023-03-06 00:25:25 +00:00
- [IOCP](https://learn.microsoft.com/en-us/windows/win32/fileio/i-o-completion-ports): Windows, Wine (version 7.13+)
Initial commit
2020-08-06 13:02:59 +00:00
Polling is done in oneshot mode, which means interest in I/O events needs to be reset after
an event is delivered if we're interested in the next event of the same kind.
Only one thread can be waiting for I/O events at a time.
## Examples
Add doc-comment to test README's examples
2020-08-06 14:12:52 +00:00
```rust,no_run
Initial commit
2020-08-06 13:02:59 +00:00
use polling::{Event, Poller};
use std::net::TcpListener;
Document non-blocking mode
2020-08-07 12:56:53 +00:00
// Create a TCP listener.
Initial commit
2020-08-06 13:02:59 +00:00
let socket = TcpListener::bind("127.0.0.1:8000")?;
Don't automatically make descriptors non-blocking This adds redundant system call overhead for file descriptors which have already been turned into non-blocking file descriptors. In addition, the polling crate doesn't need to implement platform specific code for enabling non-blocking mode. Instead, users of polling can do so using (for example) standard library methods such as TcpListener.set_nonblocking(). See https://github.com/stjepang/polling/issues/16 for more information.
2020-09-30 23:08:20 +00:00
socket.set_nonblocking(true)?;
Small cleanup
2020-10-02 14:40:09 +00:00
let key = 7; // Arbitrary key identifying the socket.
Don't automatically make descriptors non-blocking This adds redundant system call overhead for file descriptors which have already been turned into non-blocking file descriptors. In addition, the polling crate doesn't need to implement platform specific code for enabling non-blocking mode. Instead, users of polling can do so using (for example) standard library methods such as TcpListener.set_nonblocking(). See https://github.com/stjepang/polling/issues/16 for more information.
2020-09-30 23:08:20 +00:00
Initial commit
2020-08-06 13:02:59 +00:00
// Create a poller and register interest in readability on the socket.
let poller = Poller::new()?;
Separate adding and modifying of file descriptors This replaces Poller.insert() and Poller.interest() with Poller.add() and Poller.modify(), and renames Poller.remove() to Poller.delete(). The method Poller.add() is used for adding a new file descriptor, while Poller.modify() is used for updating an existing one. Poller.remove() is renamed to Poller.delete() so the naming scheme of these methods follows that of epoll, wepoll, etc. This new setup means that adding a new socket only requires a single call of Poller.add(), instead of a combination of Poller.insert() and Poller.interest(). This reduces the amount of system calls necessary, and leads to a more pleasant API. On systems that use kqueue or ports, the behaviour of Poller.add() and Poller.modify() is the same. This is because on these systems adding an already existing file descriptor will just update its configuration. This however is an implementation detail and should not be relied upon by users. Migrating to this new API is pretty simple, simply replace this: poller.insert(&socket); poller.interest(&socket, event); With this: poller.add(&socket, event); And for cases where Poller.interest() was used for updating an existing file descriptor, simply replace it will a call to Poller.modify(). See https://github.com/stjepang/polling/issues/16 and https://github.com/stjepang/polling/pull/17 for more information.
2020-10-01 19:26:44 +00:00
poller.add(&socket, Event::readable(key))?;
Initial commit
2020-08-06 13:02:59 +00:00
// The event loop.
let mut events = Vec::new();
loop {
// Wait for at least one I/O event.
events.clear();
poller.wait(&mut events, None)?;
for ev in &events {
if ev.key == key {
// Perform a non-blocking accept operation.
socket.accept()?;
// Set interest in the next readability event.
Separate adding and modifying of file descriptors This replaces Poller.insert() and Poller.interest() with Poller.add() and Poller.modify(), and renames Poller.remove() to Poller.delete(). The method Poller.add() is used for adding a new file descriptor, while Poller.modify() is used for updating an existing one. Poller.remove() is renamed to Poller.delete() so the naming scheme of these methods follows that of epoll, wepoll, etc. This new setup means that adding a new socket only requires a single call of Poller.add(), instead of a combination of Poller.insert() and Poller.interest(). This reduces the amount of system calls necessary, and leads to a more pleasant API. On systems that use kqueue or ports, the behaviour of Poller.add() and Poller.modify() is the same. This is because on these systems adding an already existing file descriptor will just update its configuration. This however is an implementation detail and should not be relied upon by users. Migrating to this new API is pretty simple, simply replace this: poller.insert(&socket); poller.interest(&socket, event); With this: poller.add(&socket, event); And for cases where Poller.interest() was used for updating an existing file descriptor, simply replace it will a call to Poller.modify(). See https://github.com/stjepang/polling/issues/16 and https://github.com/stjepang/polling/pull/17 for more information.
2020-10-01 19:26:44 +00:00
poller.modify(&socket, Event::readable(key))?;
Initial commit
2020-08-06 13:02:59 +00:00
}
}
}
```
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
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.