# Crate evaluation for 2017-08-15: mio

**URL:** <https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709>\
**Category:** libs\
**Created:** [August 3, 2017, 6:24pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709 "2017-08-03T18:24:12Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![dtolnay](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dtolnay/32/1447_2.png) [@dtolnay](https://internals.rust-lang.org/u/dtolnay)\
**Post date:** [August 3, 2017, 6:24pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/1 "2017-08-03T18:24:12Z")

</div>

# Crate evaluation for 2017-08-15: mio

For additional contribution opportunities, see the [main libz blitz thread](https://internals.rust-lang.org/t/rust-libs-blitz/5184).

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

## Links

- [https://crates.io/crates/mio](https://crates.io/crates/mio)
- [https://github.com/carllerche/mio](https://github.com/carllerche/mio)
- [https://docs.rs/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](https://public.etherpad-mozilla.org/p/rust-crate-eval-mio)

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](https://github.com/brson/rust-api-guidelines). If `[n]`, please add a brief note on the following line with an explanation. For example:

```nohighlight
  - [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`](https://github.com/rust-lang-nursery/api-guidelines) repo.

## Discussion topics

- [See bottom of etherpad](https://public.etherpad-mozilla.org/p/rust-crate-eval-mio)

---

<div class="post-metadata">

**Author:** ![jmst](https://avatars.discourse-cdn.com/v4/letter/j/41988e/32.png) [@jmst](https://internals.rust-lang.org/u/jmst)\
**Post date:** [August 3, 2017, 8:16pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/2 "2017-08-03T20:16:49Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![budziq](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/budziq/32/2289_2.png) [@budziq](https://internals.rust-lang.org/u/budziq)\
**Post date:** [August 4, 2017, 9:03am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/3 "2017-08-04T09:03:28Z")

</div>

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.

> <https://github.com/rust-lang-nursery/rust-cookbook/issues/113>
>
> Come up with ideas for nice introductory examples of using mio, possibly in combination with other crates, that would be good...

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

---

<div class="post-metadata">

**Author:** ![alexcrichton](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/alexcrichton/32/4501_2.png) [@alexcrichton](https://internals.rust-lang.org/u/alexcrichton)\
**Post date:** [August 4, 2017, 9:23am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/4 "2017-08-04T09:23:28Z")

</div>

Reading the [current set of guidelines](https://rust-lang-nursery.github.io/api-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!

---

<div class="post-metadata">

**Author:** ![KodrAus](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kodraus/32/2816_2.png) [@KodrAus](https://internals.rust-lang.org/u/KodrAus)\
**Post date:** [August 10, 2017, 1:29am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/5 "2017-08-10T01:29:00Z")

</div>

There’s this [big tracking issue](https://github.com/carllerche/mio/issues/307) 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.

---

<div class="post-metadata">

**Author:** ![KodrAus](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kodraus/32/2816_2.png) [@KodrAus](https://internals.rust-lang.org/u/KodrAus)\
**Post date:** [August 10, 2017, 6:45am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/6 "2017-08-10T06:45:56Z")

</div>

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`](https://doc.rust-lang.org/std/ops/trait.Index.html)?
  - 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.

---

<div class="post-metadata">

**Author:** ![dtolnay](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dtolnay/32/1447_2.png) [@dtolnay](https://internals.rust-lang.org/u/dtolnay)\
**Post date:** [August 13, 2017, 5:45am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/7 "2017-08-13T05:45:29Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dtolnay](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dtolnay/32/1447_2.png) [@dtolnay](https://internals.rust-lang.org/u/dtolnay)\
**Post date:** [August 15, 2017, 5:48am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/8 "2017-08-15T05:48:44Z")

</div>

I selected some topics to discuss during the libs team review of Mio tomorrow. They are listed [**below the checklist in the etherpad**](https://public.etherpad-mozilla.org/p/rust-crate-eval-mio). 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.

---

<div class="post-metadata">

**Author:** ![Dushistov](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dushistov/32/4046_2.png) [@Dushistov](https://internals.rust-lang.org/u/Dushistov)\
**Post date:** [August 15, 2017, 3:56pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/9 "2017-08-15T15:56:50Z")

</div>

@dtolnay

> [@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](https://github.com/carllerche/mio/issues/578), or [named pipes crate](https://github.com/alexcrichton/mio-named-pipes/) that duplicate a lot of code with tcp/udp code from mio windows part.

---

<div class="post-metadata">

**Author:** ![dtolnay](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dtolnay/32/1447_2.png) [@dtolnay](https://internals.rust-lang.org/u/dtolnay)\
**Post date:** [August 15, 2017, 4:21pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/10 "2017-08-15T16:21:52Z")

</div>

@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?

---

<div class="post-metadata">

**Author:** ![Dushistov](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dushistov/32/4046_2.png) [@Dushistov](https://internals.rust-lang.org/u/Dushistov)\
**Post date:** [August 15, 2017, 11:57pm UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/11 "2017-08-15T23:57:15Z")

</div>

@dtolnay

> [@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](https://github.com/kaegi/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.

> [@dtolnay](#):
>
> 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.

---

<div class="post-metadata">

**Author:** ![dtolnay](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dtolnay/32/1447_2.png) [@dtolnay](https://internals.rust-lang.org/u/dtolnay)\
**Post date:** [August 19, 2017, 3:31am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/12 "2017-08-19T03:31:22Z")

</div>

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](https://github.com/carllerche/mio/issues/655)
- [Remove the implementations of std::ops::Not](https://github.com/carllerche/mio/issues/656)
- [Document that UdpSocket::recv and recv\_from do not read from the buffer](https://github.com/carllerche/mio/issues/657)
- [Winapi in the public API of mio](https://github.com/carllerche/mio/issues/658)
- [Document that the mio::fuchsia module is unstable](https://github.com/carllerche/mio/issues/659)
- [Upgrade to a stable version of iovec](https://github.com/carllerche/mio/issues/660)
- [Consider using associated constants for the bitflag-like types](https://github.com/carllerche/mio/issues/661)
- [Implement Clone for mio::event::Iter](https://github.com/carllerche/mio/issues/662)
- [Implement Hash for Event, PollOpt, Ready](https://github.com/carllerche/mio/issues/663)
- [Method order in mio::net](https://github.com/carllerche/mio/issues/664)
- [Rustdoc examples for mio::net methods](https://github.com/carllerche/mio/issues/665)
- [Use `?` in examples, not `try!`, not unwrap()](https://github.com/carllerche/mio/issues/666)
- [SocketAddr argument to UdpSocket methods](https://github.com/carllerche/mio/issues/667)
- [Accept ToSocketAddrs](https://github.com/carllerche/mio/issues/668)
- [Debug representation of empty PollOpt](https://github.com/carllerche/mio/issues/669)
- [Handwrite Debug impl for UnixReady](https://github.com/carllerche/mio/issues/670)
- [Debug representation of opaque structs](https://github.com/carllerche/mio/issues/671)
- [Debug representation of Ready vs PollOpt](https://github.com/carllerche/mio/issues/672)
- [Multithreaded behavior of Poll](https://github.com/carllerche/mio/issues/673)
- [Single Evented on more than on Poll](https://github.com/carllerche/mio/issues/674)
- [Bound but not registered](https://github.com/carllerche/mio/issues/675)
- [Expose EPOLLEXCLUSIVE](https://github.com/carllerche/mio/issues/676)
- [Expose EPOLLWAKEUP](https://github.com/carllerche/mio/issues/677)
- [Clarify BSD support](https://github.com/carllerche/mio/issues/678)
- [Consistent case convention for name of the crate](https://github.com/carllerche/mio/issues/679)
- [Implement Index\<usize\> for Events](https://github.com/carllerche/mio/issues/681)
- [Implement IntoIterator for Events](https://github.com/carllerche/mio/issues/682)
- [Scrub for broken links](https://github.com/carllerche/mio/issues/683)
- [Consider deprecating only\_v6 and set\_only\_v6](https://github.com/carllerche/mio/issues/684)
- [Link to MSDN doc on completion ports](https://github.com/carllerche/mio/issues/685)
- [Discuss platform support in the crate-level doc](https://github.com/carllerche/mio/issues/686)

---

<div class="post-metadata">

**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\
**Post date:** [March 25, 2019, 8:28am UTC](https://internals.rust-lang.org/t/crate-evaluation-for-2017-08-15-mio/5709/13 "2019-03-25T08:28:52Z")

</div>

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