This commit is targeted at solving tokio-rs/tokio-core#12 and incorporates the
solution from tokio-rs/tokio-core#17. Namely the `need_read` and `need_write`
functions on `PollEvented` now return an error when the connected reactor has
gone away and the task cannot be blocked. This will typically naturally
translate to errors being returned by various connected I/O objects and should
help tear down the world in a clean-ish fashion.
* small doc cleanups in PollEvented
* small doc cleanups in IoToken
* improve crate level documentation
- Add links to the futures, mio and tokio-uds crates.
- Add links to various structs and types mentioned.
- use eprintln for error reporting in the example.
* improvements to the UdpSocket documentation
- Fixed links usage.
- Removed references to a no longer existing `Window` struct.
- Made notes about using functions in context of a future.
* documentation improvements to UdpFramed and UdpCodec
- Since HTTP uses TCP (QUIC aside) using it as an example in an UDP
protocol feels wrong.
- Make the note of tampering with the underlying streams more explicit.
* update reactor module level documentation
Adds an explanation of every public struct.
* expand Handle and Remote documentation
* expand net module documentation
Adds an explanation of every public struct and how they work together.
* update TcpListener documentation
Reorder the various option methods; get first then set.
Note about panicing added to poll_read.
* remove mention of none-existing future R
* improve documentation of TcpStream
* fix UdpSocket doc
This when wrong when merging various commits.
* Make Handle `Send + Sync`.
This is an initial implementation making `Handle: Send + Sync`. It uses
a `RwLock` to coordinate access to the underlying state storage. An
implementation without the lock is left to later.
This pass also leaves a lot of dead code that can be removed in later
commits.
* Remove reactor code related to message passing
The previous commit removed the need for using message passing to
communicate with the reactor. This commit removes all the unnecessary
code.
This commit adds a general-purpose method for querying the readiness of a
`PollEvented` type. This new method, `poll_ready`, takes a blanket `mio::Ready`
and tests if any part of it is ready. The purpose of this is to expose
platform-specific events through `PollReady` such as `hup` and `error` events
other than just the platform-agnostic readable/writable events.
The semanatics of this method are:
* The `poll_ready` function takes a mask, and the return value is either
`Async::Ready` with a subset of these events that are ready or `None` if none
of them are ready.
* There can be up to two tasks blocked on a `PollEvented`, so we need to pick
which one is suitable for these new events. Currently all events are routed to
the `read` task unless the writable bit is set. This is mostly only relevant
for multi-task usage or if you're manually calling `need_read` and/or
`need_write`, and hopefully the docs will cover this now.
Typically this happens automatically as the `E` in `PollEvented<E>` is an owned
reference (e.g. a `TcpStream`) where dropping that will close the resource,
automatically unregistering it from the event loop. In some situations, however,
this isn't always the case, so the deregistering needs to happen manually.
* Handle -> Remote
* Pinned -> Handle
All APIs now take a `&Handle` by default and in general can return an immediate
`io::Result` instead of an `IoFuture`. This reflects how most usage will likely
be done through handles rather than remotes, and also all previous functionality
can be recovered with a `oneshot` plus `Remote::spawn`.
Closes#15
Alex Crichton