Crate evaluation for 2017-08-15: mio

[dtolnay]

Crate evaluation for 2017-08-15: mio

For additional contribution opportunities, see the main libz blitz thread.

This post is a wiki. Feel free to edit it.

Links

• https://crates.io/crates/mio
• https://github.com/carllerche/mio
• https://docs.rs/mio

Needs your help!

Anything that is not finished still needs your help! There is no need to sign up or ask for permission.

Guidelines checklist

Legend

• [y] = guideline is adhered to, no work needed.
• [n] = guideline may need work, see comments nearby
• [/] = guideline not applicable to this crate

Checklist

Guidelines checklist

This document is collaboratively editable. Pick a few of the guidelines, compare the mio crate against them, and fill in the checklist with [y] if the crate conforms to the guideline, [n] if the crate does not conform, and [/] if the guideline does not apply to this crate. Each guideline is explained in more detail here. If [n], please add a brief note on the following line with an explanation. For example:

  - [n] Crate name is a palindrome (C-PALINDROME)
        - mio backwards is oim which is not the same as mio

API guideline updates

What lessons can we learn from mio that will be broadly applicable to other crates? Please leave a comment here with your ideas, or file an issue in the api-guidelines repo.

Discussion topics

• See bottom of etherpad

[jmst]

The multithreading situation in general seems quite unclear at least from the documentation, and the implementation probably needs to be adjusted too:

1. Can multiple threads call poll on the same Poll? What happens? The documentation says nothing.
2. Can a single Evented be registered on more than one Poll? What happens? The documentation doesn’t seem to clearly say anything.
3. The documentation says “Unless otherwise specified, the caller should assume that once an Evented handle is registered with a Poll instance, it is bound to that Poll instance for the lifetime of the Evented handle. This remains true even if the Evented handle is deregistered from the poll instance using deregister.”. It’s not clear what this means at all, in particular what being “bound” but not registered means, why this is the case, and why this limitation can’t be avoided with a better implementation.
4. EPOLLEXCLUSIVE is not exposed, which is required for some multithreading patterns.

Also, EPOLLWAKEUP is not exposed and even though it’s a niche feature it should be exposed.

Finally, the git readme says that NetBSD is supported, but doesn’t mention FreeBSD, while the documentation mentions that kqueue is used on FreeBSD but doesn’t mention NetBSD.

[budziq]

Hi I see that the cookbook related information was removed. I guess that is was intentional as mio might not be best suited for self contained clean snippets for application programmer consumption. On the other hand, we already have a tracking issue in the cookbook, so I’m referencing it for the sake of completeness.

Issue: Cookbook ideas for mio

Should we just remove this tracking issue? What do you think @dtolnay?

[alexcrichton]

Reading the current set of guidelines I was actually a little surprised! It looks like we don’t have a section on “Portability” which may be great to flesh out when talking about the mio crate, which is chock-full of portability gotchas.

Some thoughts I’d have on the topic of portability:

• First-and-foremost, how should we recommend platform-specific functionality is exposed? The crate currently uses std-style extension modules, but we’ve found that this doesn’t always work great in the ecosystem. Should we use Cargo features instead?
• We should probably explicitly document that all APIs should be “portable to tier 1 platforms” by default. What exactly “portable” means and what exactly “tier 1” means is a bit up for debate, though. Some things that mio does, though is:
  • works on Windows/Mac/Linux
  • goes above and beyond to try to provide consistency across platforms, not having one be accidentally “more featureful”
  • at the same time, exposing the underlying abilities of each platform where possible
• For crate organization, we may want to specify how one creates, for example, a windows specific implementation and a unix specific implementation. I’ve seen a lot of ways to do this but we may want to just pick one!

[KodrAus]

There’s this big tracking issue for clarifying mio's behaviour for various scenarios. It hasn’t seen any action for the last 12 months though so some of those points might already be done.

[KodrAus]

I’ve tried to make a start on the checklist but haven’t made a whole lot of progress. There’s a lot to this crate so grabbed some random notes as I was going (not organised or filtered or anything):

Random notes from poking around mio on Windows

• There’s inconsistency between references to mio in the docs: mio vs Mio
• Will the with-deprecated feature and releated code disappear in 1.0?
• Should Events implement Index?
  • Has anyone missed this? Is get being called directly, or just being iterated?
• Broken link or missing code block around readiness state in docs for Event
• Should Ready be named Readiness?
  • Probably not worthwhile. It’s more letters
• Examples using unwrap
• How much does mio try to track std with its TcpStream and TcpListener APIs?
  • Is there a reason for TcpListener to use &SocketAddrs rather than A: ToSocketAddrs? Performance? Only valid for a single address?
  • The only_v6 and set_only_v6 methods on std::TcpListener are deprecated. Should they be deprecated in mio too?
  • From the docs for TcpListener and TcpStream it’s not really clear which ones are std::net and which ones are mio::net
• Need error sections on most docs
• Need some examples for UDP
• The example for Token is bigger than I was expecting. I think it could be organised a bit more around Token so it’s easier to grok
• Broken links for set_readiness and portability notes in docs for Registration
• Broken links for Registration and Poll in docs for SetReadiness
• Should the root docs talk more about supported platforms? There’s details in the docs for Poll under implementation notes
• An external link to an MSDN doc on completion ports might be useful in the windows module

I’ll run through some more over the next few days. Hopefully we can get some more eyes on the checklist.

[dtolnay]

I think it is in scope for the cookbook to help users decide what level of the async stack they want to operate at. For example I can imagine a dedicated async chapter showing characteristic code for mio, tokio, futures, async hyper, and gotham so users can get a sense of what is most appropriate for their use case. I closed the cookbook tracking issue because I don’t think we are ready for that yet, but let’s follow up later as the relevant parts of the ecosystem approach stability.

[dtolnay]

I selected some topics to discuss during the libs team review of Mio tomorrow. They are listed below the checklist in the etherpad. If anyone has other topics they feel would be important for the libs team to discuss in person, please add them there.

Thanks for all the great feedback in this thread and in the checklist! We can still use some more eyes on Mio, so keep it coming. I will categorize and file issues in Mio’s issue tracker after the meeting so that we follow up on everything.

[Dushistov]

@dtolnay

If anyone has other topics they feel would be important for the libs team to discuss in person, please add them there.

I’m interesting in topic “Windows vs others”. Windows async I/O is different and this cause a lot of troubles if you want to use mio for not TCP or UDP sockets, see for example bluetooth sockets issue, or named pipes crate that duplicate a lot of code with tcp/udp code from mio windows part.

[dtolnay]

@Dushistov to me it looks like that was resolved in the github issue. The maintainers prioritize keeping the API surface small but would be open to providing the necessary duplication in another crate owned by someone else. Was there an aspect of it that you think needs more detail, or something that cannot be factored out the way that they suggest?

[Dushistov]

@dtolnay

to me it looks like that was resolved in the github issue. The maintainers prioritize keeping the API surface small but would be open to providing the necessary duplication in another crate owned by someone else.

I would not call this issue was resolved, it was closed - yes, but not near to resolved.

I just wrote my own mio for this particular case - bluetooth sockets on windows. Because of resulted own mio code size is smaller then possible duplication of mio/src/sys/windows and so required less efforts to support.

And as result I was not able to add win32 support to bluetooth-serial-port, because of it uses mio for linux case, and usage of another variant of mio for windows break the whole idea of crossplatform bluetooth-serial-library.

Was there an aspect of it that you think needs more detail, or something that cannot be factored out the way that they suggest?

Possible solution will be to extract udp/tcp sockets into separate crate add bluetooth sockets may be named pipes and supports them as whole thing. But as I understand, mio team suggest just copy/paste udp/tcp sockets code.

[dtolnay]

Here are the issues that came out of this review. We are going to need lots of help!

• Drop the with-deprecated cfg and everything behind it
• Remove the implementations of std::ops::Not
• Document that UdpSocket::recv and recv_from do not read from the buffer
• Winapi in the public API of mio
• Document that the mio::fuchsia module is unstable
• Upgrade to a stable version of iovec
• Consider using associated constants for the bitflag-like types
• Implement Clone for mio::event::Iter
• Implement Hash for Event, PollOpt, Ready
• Method order in mio::net
• Rustdoc examples for mio::net methods
• Use ? in examples, not try!, not unwrap()
• SocketAddr argument to UdpSocket methods
• Accept ToSocketAddrs
• Debug representation of empty PollOpt
• Handwrite Debug impl for UnixReady
• Debug representation of opaque structs
• Debug representation of Ready vs PollOpt
• Multithreaded behavior of Poll
• Single Evented on more than on Poll
• Bound but not registered
• Expose EPOLLEXCLUSIVE
• Expose EPOLLWAKEUP
• Clarify BSD support
• Consistent case convention for name of the crate
• Implement Index<usize> for Events
• Implement IntoIterator for Events
• Scrub for broken links
• Consider deprecating only_v6 and set_only_v6
• Link to MSDN doc on completion ports
• Discuss platform support in the crate-level doc

[system]

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.