Consider defaulting Tokio features to off instead of on.

[carllerche]

As per #1318, Tokio has been merged into a single crate and components are split by feature flag. Now, with all features enabled, the tokio crate is quite heavy.

Regardless of the direction, two things will happen:

• documentation: the required feature flag for all components will be documented similar to how Tonic does this (see transport module here: https://docs.rs/tonic/0.1.0-alpha.6/tonic/).
• meta feature: A full feature flag will be provided that enables all Tokio feature flags.

The question is, should default include all features, no features, or some features.

Default on

One of the main drawbacks mentioned in #1318 was that, when features are enabled by default, libraries will accidentally depend on more features than necessary. Doing so will force these features to be enabled by consumers of the library. Also, the end user can accidentally use features that were enabled by the dependency. When the dependency changes its feature flags, the application breaks as the required features are no longer available.

Default off

An alternative would be to default to no feature flags enabled by default. In this case, depending on tokio will only enable core traits (AsyncRead, AsyncWrite, ToSocketAddrs) and an empty Runtime type that doesn't do much when used. Getting started guides, examples, the README would instruct users to depend on tokio as:

tokio = { version = "0.2.0", features = ["full"] }

Libraries will be instructed to pick only the features they require. The primary drawback of this strategy is that it adds a bump to the getting started flow.

Default some

A middle ground would be to define a subset of features that should be enabled by default. It is unclear how to pick the features to enable by default as different Tokio users use significantly different feature sets. Because the choice is arbitrary, the end user will have no way to intuit if a feature is enabled by default or not.

[jedisct1]

I'd vote for Default Off.

Having to add the set of features required by an example is unlikely to be an issue.

[anton-dutov]

IMO
default off
Better choice - Usually i use small subset of tokio features, may differs per project

default on
Bad choice, i think nobody use all features in single project

[tobz]

Proposal: end user vs author crates

There are two primary usage patterns: import tokio and have everything "just work" vs import only the absolutely required bits on tokio.

The first group typically consists of new users or people who are not bothered by extra dependencies, and they simply want to import one crate and be able to run examples, focus on building their application, and so on. The second group involves users who are either conscious of the extra dependencies being included that their applications do not require, or they're library authors looking to only pull in the absolute minimum of APIs to expose their crate's functionality.

Running with this idea of wanting to support both major use cases, I propose we expose two main crates: tokio and tokio-inner. (inner is just a filler word, really).

What would happen is that tokio-inner would effectively become what tokio is today: holding the majority of modules/code with feature flag differentiation. In turn, tokio would then re-export from tokio-inner. Crucially, tokio-inner would not have default features, while tokio would have defaults comparable to the existing full feature flag.

In this way, end users could continue to use tokio with a batteries-included set of default features, while more discerning users could choose to use tokio-inner and feature flag only what they needed.

Open questions:

• would this technically work? (I think it would, but I'm not a cargo deps resolution expert)
• do we actually think users in the "discerning" camp would be OK having to use a differently-named crate?
• is there any versioning risk? (conceivably, both crates can be released in lockstep, but maybe not?)

[dekellum]

I also think default-off is a better choice. The heavy use of features per #1318, warrants a more conservative, explicit opt-in to features at the application level.

I also wonder if meta-features like full in particular, and possibly others like net are really beneficial vs. a complication. I'll personally avoid using those, for example, for apps that don't use udp or uds. Given good documentation, it might be better for applications to make the upfront effort to specify their full set of required features. This is made easier for first time users by having the full set of features shown in a Cargo.toml dependency example of the guide/README. Then besides just a good list of features with descriptions at top level, the rustdoc should ideally note the feature required to gain access to a given module and/or its key items, e.g. "Foo is enabled by the special-foo feature flag".

[berkus]

I'd say it's good to keep the default list to a bare necessary minimum.

full flag should be handy if you absolutely want to try everything out (also, for noobs just discovering what tokio has to offer). In the dependency graph, however, tokio is best kept to the required minimum footprint.

[swarmer]

In case of default off it will be important to make instructions about these features highly visible:

• In guides
• Probably in API docs
• in README
• For people that jump straight to the example in README, maybe add a comment in the beginning like "// this example requires the following features: ...."

[hawkw]

Running with this idea of wanting to support both major use cases, I propose we expose two main crates: tokio and tokio-inner. (inner is just a filler word, really).

how about...tokio and tokio-core 😉

[hwchen]

As mentioned in OP, default on is too heavy, default some is confusing.

I think that default off is the best, with good docs.

I also agree with some comments above; I would want the feature flag to be mentioned in the api docs, it would reduce the friction of having to jump to e.g. the readme.

[LucioFranco]

I vote default off and shim crates with tokio itself bringing in everything and core default off. Good docs are key here and we should use the doc_cfg nightly feature like we do in tonic.

[swarmer]

Isn't shim crate the same as default on in the sense that in both cases library authors need to be careful enough to do the right thing and not just depend on tokio, but with extra confusion of multiple crates?

[hawkw]

Isn't shim crate the same as default on in the sense that in both cases library authors need to be careful enough to do the right thing and not just depend on tokio, but with extra confusion of multiple crates?

IMO, having two separate crates makes the distinction clearer and is much less error-prone. If the naming and documentation makes it clear when the two crates should be used, both application and library authors get the sensible behavior by default, with a simple $CRATE_NAME = "$VERSION" dependency in their Cargo.toml. On the other hand, with a single crate, regardless of whether we default on or default off, one category of users will always get the "wrong" behavior by default.

On a more general note, I think that optimizing for new-user experience is important and worth prioritizing. So much of the other work we've done for the 0.2 release has centered around improving new-user experience and accessibility: simplifying APIs, using names that are closer to std, and providing more batteries-included options like #[tokio::main] are all examples of this. If we default to disabling everything and don't provide some kind of obvious, easily-accessed batteries-included option, I feel like the #tokio-users chat channel will quickly become inundated with a steady stream of "I tried to compile this simple demo program, but it said it couldn't find any of these APIs?"-type questions. Having a batteries-included option is important, even if no "serious" or production users actually use it, just to avoid shipping something that appears "broken" out of the box for new users. IMO, having both a default-off "core" crate and a batteries-included facade crate is the best option for providing sensible defaults to both new users and experienced "power" users.

Just my 2¢!

[dekellum]

IMO, the extra crate would be more of a complication than value in protecting new users from the feature concept. The main complication is that there would then be Cargo.toml dependency and rust code references to both crate names. For example, where would the examples live and which of the two names would they use?

New users may also be concerned by more dependencies and longer build times associated with all features, particularly when starting with a small application that only really needs minimal features.

Compare to tokio 0.1 where we needed to figure out which of many crates to depend on. Explicit features is much easier than that.

[hawkw]

Hmm, I think choosing one of two crates is much easier than figuring out a large number of Cargo features, especially for new Rust users who may not even be aware that Cargo feature flags exist.
Basic examples and "Getting Started"-type documentation intended for newcomers would suggest the use of the batteries-included facade crate, and everything would "just work" out of the box. At the end of the documentation, there could be a note that users who want to pick and choose what features they depend on can use the default-off crate.

Again, I think it's really important that for someone just getting started, adding

tokio = "0.2"

to their Cargo.toml doesn't appear to be "totally broken" out of the box.

[myrrlyn]

Speaking solely as someone who periodically attempts to write a Tokio application essentially from scratch, I am more in favor of having "drop tokio = "version" in your manifest" be sufficient to "just work", even if it pulls more than I might immediately need.

From a UX perspective, encountering a "this doesn't exist" fault every time I want to try something that forces me to go look up how to enable it, and check if I even need it, is an unpleasant pattern. I would much prefer to have too much of a dependency graph by default, and once I have a better idea of what parts of Tokio I actually need, start disabling the things I don't.

Shipping a minimal-by-default crate that requires explicit lookup and opt-in for every new feature is, at least in my opinion, a premature optimization whose benefits in build expense are not sufficient to overcome the penalties on usability and exploration.

As an analogy, std is not opt-in either, even for libraries that might not ever use the parts of std that don't exist in core and alloc. It's a better experience to just have the kitchen sink, and then start turning things off that you realize you definitely don't need, than to have to pull each new component when you realize you need it. Removing things you've discovered you don't need at the end of a cycle is, again speaking purely personally, a preferable experience to having to select the things I do need at the start; by the end, I've generally learned enough to know what I do and don't need and can act more firmly, rather than speculatively.