## Motivation
Closes#1118
Mio should be as light as possible and forwards compatible to other non-blocking
I/O strategies such as user-land sockets.
Currently, depending on Mio means that all platform-specific networking
primitives and I/O source readiness polling functionality is present by default.
If a library is interested only in networking primitives but aims to provide an
other strategy for I/O source readiness polling, there is no way to disable the
provided implementation.
If a library is interested in the provided I/O source readiness polling
implementations, but only uses the TCP networking types, the UDP and UDS types
are also still provided.
This change proposes that Mio by default provides an API shim for its common
types such as `Poll`, `Events`, etc. Attempting to use them will result in a
panic. TCP, UDP, and UDS networking types are **not** present by default and
require feature flags to opt-in.
## Solution
### Overview
Below are the four feature flags that Mio now includes as opt-in features. By
default, no functionality is provided--only an API shim.
- `os-poll`: Provide the cross-platform implementations of `Poll`. This is
currently epoll, IOCP, or kqueue depending on the platform.
- `os-util`: Provide the cross-platform adapters for the platform's underlying
I/O source that implements `event::Source`. Currently, only Unix provides it's
`SourceFd` type. There are proposed solutions for a Windows equivalent being
worked on.
- `tcp`: Provide the TCP types and implementations
- `udp`: Provide the UDP types and implementations
- `uds`: Provide the UDS types and implementations. Currently, only Unix
provides types and implementations for this feature.
The above feature flags can be used in any combination. If a library opts in to
`os-poll` and `tcp`, then the `Poll` and TCP implementations will be provided.
Later, the library could provide it's own `Poll` implementation and opt-out of
`os-poll`. It could alternatively opt-in to UDP at a later point without issue.
### Details
Mio now has the following cfg macros: `cfg_os_poll`, `cfg_not_os_poll`,
`cfg_net`, `cfg_tcp`, `cfg_udp`, `cfg_uds`, `cfg_any_os_util` that conditionally
provide the related types and implementations. *(If any of these names are not
obvious about what they provide, please let me know!)*.
The macros--again similar to Tokio--conditionally provide shell types that
**panic upon use**, or hide/expose methods on types an API shim should not
provide (e.g. `Poll::new`).
## Tips for Review
This change touches a lot of files, but there are no intended functional or
behavioral changes. I would recommend first looking at what types are provided
by the root-level `lib.rs` or changes in the `mod.rs` files. *(If any of the
`mod.rs` files are not clear about what they conditionally expose, please let me
know!)*.
Next, I would look at the methods that are now conditionally provided on the
types. These are mostly confined to the OS specific `Poll` implementations, but
there are a few exceptions.
Finally, there are some further changes that reorganize `impl`s or move `use`
statements due to being conditionally used. Because this change is ultimately a
"refactor", I found myself moving some blocks of code around to group with
similar `impl`s and such. I'd like to keep those as part of this change (instead
of a separate PR), but please me know if have questions/concerns about any of
those.
Signed-off-by: Kevin Leimkuhler <kleimkuhler@icloud.com>
Generally speaking event source shouldn't concurrently need to be
(re/de)-registered. Even though on most platforms this is possible it
makes it more complex on platforms that need user space bookkeeping,
such as Windows.
Changes the structure a bit to match the TCP server example. Enables
logging and prints how the server can be accessed, also matching the TCP
server example
Thomas de Zeeuw