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.
The multithreading situation in general seems quite unclear at least from the documentation, and the implementation probably needs to be adjusted too:
Can multiple threads call poll on the same Poll? What happens? The documentation says nothing.
Can a single Evented be registered on more than one Poll? What happens? The documentation doesn’t seem to clearly say anything.
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.
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.
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.
Should we just remove this tracking issue? What do you think @dtolnay?
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!
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.
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?
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.
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.
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.
@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?
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.
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.