commit ac8b7de45687815386a6ebcd23c07048d1826f38
author Alex Crichton <alex@alexcrichton.com> Sat Dec 10 12:00:09 2016 -0800
committer Alex Crichton <alex@alexcrichton.com> Wed Dec 14 14:56:57 2016 -0800
tree 31ee0ffeaf1608c0cc50cb777079501f1afddf3c
parent 31c2298c79f2ebbbd7af4f6086cd4221fe646dc1

Allow registration of custom handles on Windows

This commit intends to extend the functionality of mio on Windows to support
custom handles being registered with the internal IOCP object. This in turn
should unlock the ability to work with named pipes, filesystem changes, or any
other IOCP-enabled object on Windows. Named pipes are in particular quite
important as they're often a foundational IPC mechanism on Windows.

This support is provided by exporting two new types in a `windows` module. A
`Binding` serves as the ability to register with the actual IOCP port in an
`Evented` implementation. Internally the `Binding` keeps track of what it
was last associated with to implement IOCP semantics. This may one day be
possible to make a zero-sized-type.

The second type, `Overlapped`, is exported as a contract that all overlapped I/O
operations must be executed with this particular type. This ensures that after
an event is received from an IOCP object we know what to do with it. Essentially
this is just a `OVERLAPPED` with a function pointer after it.

Along the way this exposes the `winapi` crate as a public dependency of `mio`.
The `OVERLAPPED_ENTRY` and `OVERLAPPED` types in `winapi` are exposed through
the `Overlapped` type that mio itself exports.

I've implemented [bindings to named pipes][bindings] and I've also got a
proof-of-concept [process management library][tokio-process] using these
bindings. So far it seems that this support in mio is sufficient for building up
these applications, and it all appears to be working so far.

I personally see this as a much bigger committment on the mio side of things
than the Unix implementation. The `EventedFd` type on Unix is quite small and
minimal, but the `Overlapped` and `binding` types on Windows are just
pieces of a larger puzzle when dealing with overlapped operations. Questions
about ownership of I/O objects arise along with the method of handling
completion status notifications. For now this is essentially binding mio to
stick to at least the same strategy for handling IOCP for the 0.6 series. A
major version bump of mio could perhaps change these semantics, but it may be
difficult to do so.

It seems, though, that the Windows semantics are unlikely to change much in the
near future. The overhead seems to have essentially reached its limit ("bolting
readiness on completion") and otherwise the ownership management seems
negligible.

Closes #252
Closes #320