Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow registration of custom handles on Windows #504

Merged
merged 1 commit into from
Dec 18, 2016

Conversation

alexcrichton
Copy link
Contributor

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
Registration serves as the ability to register with the actual IOCP port in an
Evented implementation. Internally the Registration 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 miow crate as a public dependency of mio. The
CompletionStatus and Overlapped types in miow 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 Registration 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

@alexcrichton
Copy link
Contributor Author

Note that I've also tried to be sure to thoroughly document everything wherever possible, but if there are pieces missing just let me know!

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 tokio-rs#252
Closes tokio-rs#320
@alexcrichton
Copy link
Contributor Author

After some discussion offline I've switched to be more conservative by only exposing winapi types rather than the miow types, so miow will now continue to be a private dependency.

@carllerche
Copy link
Member

Lgtm

@alexcrichton alexcrichton merged commit ac8b7de into tokio-rs:master Dec 18, 2016
@alexcrichton alexcrichton deleted the custom-iocp branch May 20, 2017 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants