tokio: Please document that Tokio doesn't work with `fork()`

Version N/A - checked in current master and at tokio-1.14.0

Platform N/A

Description

Over the last few days I’ve seen two people in the #tokio-users Discord having issues with forking. It seems the interactions between fork() and the runtime are not documented at all. This has shown to stumble users and as such I’m filing this as a documentation bug.

Out of curiosity I have cloned the repository and looked for mentions of fork:

jaskij@jaskij-pc [16:40:00] [~/projects/rust/tokio] [master]
-> % rg -i fork
tokio/src/process/mod.rs
616:    /// `fork`. This primarily means that any modifications made to memory on
620:    /// other threads perhaps still running when the `fork` was run).

tokio/tests/process_kill_on_drop.rs
18:       # Fork another child that won't get killed

As you can see, the only mention is in process::pre_exec() and a test for that mod.

While fork() after spawning threads is afaik not something broadly supported and could be somewhat expected as common knowledge, the current_thread runtime also doesn’t work with fork() depending on features used.

As @Darksonn mentioned in Discord, fork()ing support in Tokio isn’t well investigated, so including a call for help in the docs might be an option too.

That said, use cases for both fork and tokio seem either rare, or with an easy workaround:

  • rare: severe isolation, like esrlabs/northstar
  • easy workaround: daemonization for long running services: this is worked around by forking before running the tokio runtime

About this issue

  • Original URL
  • State: open
  • Created 5 years ago
  • Reactions: 15
  • Comments: 17 (8 by maintainers)

Most upvoted comments

I’m open to improving the situation. Shutting down all runtimes, calling fork, and then starting new runtimes afterwards seems possible to support.

Fork is only supported in the following two cases:

  1. The call to fork happens before the parent process uses Tokio in any way.
  2. The child process does not touch Tokio in any way.

Process B will not be able to use Tokio.

No, there is currently no way to reset them.