Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve docs for tokio_unstable. #4524

Merged
merged 7 commits into from Feb 25, 2022
Merged

Improve docs for tokio_unstable. #4524

merged 7 commits into from Feb 25, 2022

Conversation

NfNitLoop
Copy link
Contributor

Motivation

Ran into some headaches getting tokio_unstable working, since I'd never had to deal with --cfg directly before. I was told "PRs welcome" in the Tokio Discord, so here I am. :)

Solution

Mostly I added an example .cargo/config.toml for others who run into this.

But the existing docs seemed really focused on "these feature flags are enabled by tokio_unstable", but now tioko_unstable also enables JoinSet, so I reworked it a bit to call that out explicitly.

I didn't want to blather on too much in rustdoc about "this is why we can't just use a crate feature", so I just linked to the writeup I posted about it on the Rust internals forum. Is that weird? 😅

@NfNitLoop
Improve docs for tokio_unstable.
435a82f 
* Mention JoinSet.
* Example config.toml.
@NfNitLoop
Copy link
Contributor Author

It looks like the freebsd docs test failed because it doesn't enable the tokio_unstable flag:
https://github.com/tokio-rs/tokio/pull/4524/checks?check_run_id=5281388263

I guess I assumed since the docs on docs.rs include tokio_unstable features, doc builds would include that. Hmm, what's the preferred fix here?

  • Don't link to unstable features
  • (Maybe) use an old-style link that will just be broken when tokio_unstable isn't set
  • Just don't link and require the user to search for JoinSet.

@NfNitLoop
Enable --cfg tokio_unstable on FreeBSD doc builds.
40c16ee 
It's already enabled on other doc builds.
@NfNitLoop
Copy link
Contributor Author

Aha, there's a 4th option. --cfg tokio_unstable was already enabled in a lot of CI stuff, so I added it to the FreeBSD docs build.

I'm guessing -Dwarnings is there to fail on doc warnings, and it's being run with --all-features so... I assume we should test all the features, even those behind magical not-feature feature flags. :p

Though, I just realized ... I don't think the GitHub ci.yml workflow enables unstable_tokio for docs either.

Sorry for all the noise here. I can't run cargo +nightly doc --all-features locally on Windows so I'm having to lean heavily on the CI to discover these things.

Darksonn
Darksonn reviewed Feb 22, 2022
View reviewed changes
tokio/src/lib.rs Outdated
//!
//! To enable these features, the `--cfg tokio_unstable` must be passed to
//! `rustc` when compiling. This is easiest done using the `RUSTFLAGS` env
//! variable: `RUSTFLAGS="--cfg tokio_unstable"`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably show a full invocation to cargo build. Preferably for both unix and windows if different.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This blurb was previously existing (from 79d25b0) and just got reformatted with my changes. I just left it in as-is.

I'm wary about trying to explain how to use environment variables and cargo build on various systems, though. (For example, on Windows it's different depending on whether you're using the command prompt or PowerShell. Not to mention the various *nix shells.)

Copy link
Contributor

@Darksonn Darksonn Feb 23, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't have to document every possible shell out there, but I still think that including some common variants is useful. I suspect that many people will not know how to specify environment variables.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, added *nix + Windows PowerShell examples.

@NfNitLoop
Copy link
Contributor Author

NfNitLoop commented Feb 23, 2022 •
edited

OK, doc + rustfmt fixes.

I hope y'all do a squash merge when you merge this. 😅

Or I can squash them if you prefer.

Oh nevermind, https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md#commit-squashing recommends not squashing during review. 👍

@Darksonn
Copy link
Contributor

Yes, we will squash your change when we merge it.

@Darksonn Darksonn added A-tokio Area: The main tokio crate T-docs Topic: documentation labels Feb 23, 2022
@NfNitLoop
Copy link
Contributor Author

On the previous build I saw an odd error in wasm tests that doesn't seem related to these doc changes. Flaky test? Or actually related to doc changes?

@Darksonn
Copy link
Contributor

The test you referred to was broken on master for about a day and fixed in #4527.

@LucioFranco
Copy link
Member

Seems we just need a rebase and we can merge?

@NfNitLoop
Copy link
Contributor Author

@LucioFranco Is that something I need to do? I think you can just have GitHub squash commits as an option when you merge:

https://images.app.goo.gl/4Z879rghVKAygbp56

@LucioFranco LucioFranco merged commit 4485921 into tokio-rs:master Feb 25, 2022
@LucioFranco
Copy link
Member

Oh yup we can merge! Thanks for the contribution @NfNitLoop!

hawkw added a commit that referenced this pull request Apr 27, 2022
@hawkw
tokio: prepare to release v1.18.0
6fcaea7 
# 1.18.0 (April 27, 2022)

This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and
`tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s
for uniquely identifying a task, and `AbortHandle` for remotely cancelling a
task), as well as a number of bugfixes.

### Fixed

- blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616])
- macros: fix `select` macro to process 64 branches ([#4519])
- net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582])
- runtime: recover when OS fails to spawn a new thread ([#4485])

### Added

- macros: support setting a custom crate name for `#[tokio::main]` and
  `#[tokio::test]` ([#4613])
- net: add `UdpSocket::peer_addr` ([#4611])
- net: add `try_read_buf` method for named pipes ([#4626])
- signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540])
- signal: add support for signals up to `SIGRTMAX` ([#4555])
- sync: add `watch::Sender::send_modify` method ([#4310])
- sync: add `broadcast::Receiver::len` method ([#4542])
- sync: add `watch::Receiver::same_channel` method ([#4581])
- sync: implement `Clone` for `RecvError` types ([#4560])

### Changed

- update `nix` to 0.24, limit features ([#4631])
- update `mio` to 0.8.1 ([#4582])
- macros: rename `tokio::select!`'s internal `util` module ([#4543])
- runtime: use `Vec::with_capacity` when building runtime ([#4553])

### Documented

- improve docs for `tokio_unstable` ([#4524])
- runtime: include more documentation for thread_pool/worker ([#4511])
- runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567])
- time: clarify platform specific timer resolution ([#4474])
- signal: document that `Signal::recv` is cancel-safe ([#4634])
- sync: `UnboundedReceiver` close docs ([#4548])

### Unstable

The following changes only apply when building with `--cfg tokio_unstable`:

- task: add `task::Id` type ([#4630])
- task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530],
  [#4640])
- task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531])
- task: fix broken link in `AbortHandle` RustDoc ([#4545])
- metrics: add initial IO driver metrics ([#4507])

[#4616]: #4616
[#4519]: #4519
[#4582]: #4582
[#4485]: #4485
[#4613]: #4613
[#4611]: #4611
[#4626]: #4626
[#4540]: #4540
[#4555]: #4555
[#4310]: #4310
[#4542]: #4542
[#4581]: #4581
[#4560]: #4560
[#4631]: #4631
[#4582]: #4582
[#4543]: #4543
[#4553]: #4553
[#4524]: #4524
[#4511]: #4511
[#4567]: #4567
[#4474]: #4474
[#4634]: #4634
[#4548]: #4548
[#4630]: #4630
[#4530]: #4530
[#4640]: #4640
[#4531]: #4531
[#4545]: #4545
[#4507]: #4507
hawkw added a commit that referenced this pull request Apr 27, 2022
@hawkw
tokio: prepare to release v1.18.0
b8ffe77 
# 1.18.0 (April 27, 2022)

This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and
`tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s
for uniquely identifying a task, and `AbortHandle` for remotely cancelling a
task), as well as a number of bugfixes.

### Fixed

- blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616])
- macros: fix `select` macro to process 64 branches ([#4519])
- net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582])
- runtime: recover when OS fails to spawn a new thread ([#4485])

### Added

- macros: support setting a custom crate name for `#[tokio::main]` and
  `#[tokio::test]` ([#4613])
- net: add `UdpSocket::peer_addr` ([#4611])
- net: add `try_read_buf` method for named pipes ([#4626])
- signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540])
- signal: add support for signals up to `SIGRTMAX` ([#4555])
- sync: add `watch::Sender::send_modify` method ([#4310])
- sync: add `broadcast::Receiver::len` method ([#4542])
- sync: add `watch::Receiver::same_channel` method ([#4581])
- sync: implement `Clone` for `RecvError` types ([#4560])

### Changed

- update `nix` to 0.24, limit features ([#4631])
- update `mio` to 0.8.1 ([#4582])
- macros: rename `tokio::select!`'s internal `util` module ([#4543])
- runtime: use `Vec::with_capacity` when building runtime ([#4553])

### Documented

- improve docs for `tokio_unstable` ([#4524])
- runtime: include more documentation for thread_pool/worker ([#4511])
- runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567])
- time: clarify platform specific timer resolution ([#4474])
- signal: document that `Signal::recv` is cancel-safe ([#4634])
- sync: `UnboundedReceiver` close docs ([#4548])

### Unstable

The following changes only apply when building with `--cfg tokio_unstable`:

- task: add `task::Id` type ([#4630])
- task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530],
  [#4640])
- task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531])
- task: fix broken link in `AbortHandle` RustDoc ([#4545])
- metrics: add initial IO driver metrics ([#4507])

[#4616]: #4616
[#4519]: #4519
[#4582]: #4582
[#4485]: #4485
[#4613]: #4613
[#4611]: #4611
[#4626]: #4626
[#4540]: #4540
[#4555]: #4555
[#4310]: #4310
[#4542]: #4542
[#4581]: #4581
[#4560]: #4560
[#4631]: #4631
[#4582]: #4582
[#4543]: #4543
[#4553]: #4553
[#4524]: #4524
[#4511]: #4511
[#4567]: #4567
[#4474]: #4474
[#4634]: #4634
[#4548]: #4548
[#4630]: #4630
[#4530]: #4530
[#4640]: #4640
[#4531]: #4531
[#4545]: #4545
[#4507]: #4507
@hawkw hawkw mentioned this pull request Apr 27, 2022
Merged
hawkw added a commit that referenced this pull request Apr 27, 2022
@hawkw
tokio: prepare to release v1.18.0 (#4641)
4818343 
# 1.18.0 (April 27, 2022)

This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and
`tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s
for uniquely identifying a task, and `AbortHandle` for remotely cancelling a
task), as well as a number of bugfixes.

### Fixed

- blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616])
- macros: fix `select` macro to process 64 branches ([#4519])
- net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582])
- runtime: recover when OS fails to spawn a new thread ([#4485])

### Added

- macros: support setting a custom crate name for `#[tokio::main]` and
  `#[tokio::test]` ([#4613])
- net: add `UdpSocket::peer_addr` ([#4611])
- net: add `try_read_buf` method for named pipes ([#4626])
- signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540])
- signal: add support for signals up to `SIGRTMAX` ([#4555])
- sync: add `watch::Sender::send_modify` method ([#4310])
- sync: add `broadcast::Receiver::len` method ([#4542])
- sync: add `watch::Receiver::same_channel` method ([#4581])
- sync: implement `Clone` for `RecvError` types ([#4560])

### Changed

- update `nix` to 0.24, limit features ([#4631])
- update `mio` to 0.8.1 ([#4582])
- macros: rename `tokio::select!`'s internal `util` module ([#4543])
- runtime: use `Vec::with_capacity` when building runtime ([#4553])

### Documented

- improve docs for `tokio_unstable` ([#4524])
- runtime: include more documentation for thread_pool/worker ([#4511])
- runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567])
- time: clarify platform specific timer resolution ([#4474])
- signal: document that `Signal::recv` is cancel-safe ([#4634])
- sync: `UnboundedReceiver` close docs ([#4548])

### Unstable

The following changes only apply when building with `--cfg tokio_unstable`:

- task: add `task::Id` type ([#4630])
- task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530],
  [#4640])
- task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531])
- task: fix broken link in `AbortHandle` RustDoc ([#4545])
- metrics: add initial IO driver metrics ([#4507])

[#4616]: #4616
[#4519]: #4519
[#4582]: #4582
[#4485]: #4485
[#4613]: #4613
[#4611]: #4611
[#4626]: #4626
[#4540]: #4540
[#4555]: #4555
[#4310]: #4310
[#4542]: #4542
[#4581]: #4581
[#4560]: #4560
[#4631]: #4631
[#4582]: #4582
[#4543]: #4543
[#4553]: #4553
[#4524]: #4524
[#4511]: #4511
[#4567]: #4567
[#4474]: #4474
[#4634]: #4634
[#4548]: #4548
[#4630]: #4630
[#4530]: #4530
[#4640]: #4640
[#4531]: #4531
[#4545]: #4545
[#4507]: #4507

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
crapStone pushed a commit to Calciumdibromid/CaBr2 that referenced this pull request May 1, 2022
Update Rust crate tokio to 1.18.0 (#1327)
0201aa5 
This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
| [tokio](https://tokio.rs) ([source](https://github.com/tokio-rs/tokio)) | dependencies | minor | `1.17.0` -> `1.18.0` |
| [tokio](https://tokio.rs) ([source](https://github.com/tokio-rs/tokio)) | dev-dependencies | minor | `1.17.0` -> `1.18.0` |

---

### Release Notes

<details>
<summary>tokio-rs/tokio</summary>

### [`v1.18.0`](https://github.com/tokio-rs/tokio/releases/tokio-1.18.0)

[Compare Source](tokio-rs/tokio@tokio-1.17.0...tokio-1.18.0)

##### 1.18.0 (April 27, 2022)

This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and
`tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s
for uniquely identifying a task, and `AbortHandle` for remotely cancelling a
task), as well as a number of bugfixes.

##### Fixed

-   blocking: add missing `#[track_caller]` for `spawn_blocking` ([#&#8203;4616](tokio-rs/tokio#4616))
-   macros: fix `select` macro to process 64 branches ([#&#8203;4519](tokio-rs/tokio#4519))
-   net: fix `try_io` methods not calling Mio's `try_io` internally ([#&#8203;4582](tokio-rs/tokio#4582))
-   runtime: recover when OS fails to spawn a new thread ([#&#8203;4485](tokio-rs/tokio#4485))

##### Added

-   macros: support setting a custom crate name for `#[tokio::main]` and
    `#[tokio::test]` ([#&#8203;4613](tokio-rs/tokio#4613))
-   net: add `UdpSocket::peer_addr` ([#&#8203;4611](tokio-rs/tokio#4611))
-   net: add `try_read_buf` method for named pipes ([#&#8203;4626](tokio-rs/tokio#4626))
-   signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#&#8203;4540](tokio-rs/tokio#4540))
-   signal: add support for signals up to `SIGRTMAX` ([#&#8203;4555](tokio-rs/tokio#4555))
-   sync: add `watch::Sender::send_modify` method ([#&#8203;4310](tokio-rs/tokio#4310))
-   sync: add `broadcast::Receiver::len` method ([#&#8203;4542](tokio-rs/tokio#4542))
-   sync: add `watch::Receiver::same_channel` method ([#&#8203;4581](tokio-rs/tokio#4581))
-   sync: implement `Clone` for `RecvError` types ([#&#8203;4560](tokio-rs/tokio#4560))

##### Changed

-   update `mio` to 0.8.1 ([#&#8203;4582](tokio-rs/tokio#4582))
-   macros: rename `tokio::select!`'s internal `util` module ([#&#8203;4543](tokio-rs/tokio#4543))
-   runtime: use `Vec::with_capacity` when building runtime ([#&#8203;4553](tokio-rs/tokio#4553))

##### Documented

-   improve docs for `tokio_unstable` ([#&#8203;4524](tokio-rs/tokio#4524))
-   runtime: include more documentation for thread_pool/worker ([#&#8203;4511](tokio-rs/tokio#4511))
-   runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#&#8203;4567](tokio-rs/tokio#4567))
-   time: clarify platform specific timer resolution ([#&#8203;4474](tokio-rs/tokio#4474))
-   signal: document that `Signal::recv` is cancel-safe ([#&#8203;4634](tokio-rs/tokio#4634))
-   sync: `UnboundedReceiver` close docs ([#&#8203;4548](tokio-rs/tokio#4548))

##### Unstable

The following changes only apply when building with `--cfg tokio_unstable`:

-   task: add `task::Id` type ([#&#8203;4630](tokio-rs/tokio#4630))
-   task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#&#8203;4530](tokio-rs/tokio#4530)],
    \[[#&#8203;4640](tokio-rs/tokio#4640))
-   task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#&#8203;4531](tokio-rs/tokio#4531))
-   task: fix broken link in `AbortHandle` RustDoc ([#&#8203;4545](tokio-rs/tokio#4545))
-   metrics: add initial IO driver metrics ([#&#8203;4507](tokio-rs/tokio#4507))

</details>

---

### Configuration

📅 **Schedule**: At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about these updates again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, click this checkbox.

---

This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Co-authored-by: cabr2-bot <cabr2.help@gmail.com>
Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1327
Reviewed-by: crapStone <crapstone@noreply.codeberg.org>
Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>
Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Darksonn Darksonn Darksonn approved these changes

@LucioFranco LucioFranco LucioFranco approved these changes

Assignees
No one assigned
Labels
A-tokio Area: The main tokio crate T-docs Topic: documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@NfNitLoop @Darksonn @LucioFranco