From ecb5125a6787b9d8eb818b1b00973bcd55ae77c0 Mon Sep 17 00:00:00 2001
From: Mukhammedali Berektassuly
 <108051441+Berektassuly@users.noreply.github.com>
Date: Wed, 10 Jun 2026 17:05:27 +0500
Subject: [PATCH] runtime: document interaction with fork() (#8202)

---
 tokio/src/runtime/mod.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs
index 2b3f0ad9b..05bb5fa6e 100644
--- a/tokio/src/runtime/mod.rs
+++ b/tokio/src/runtime/mod.rs
@@ -236,6 +236,20 @@
 //! guaranteed to have been terminated. See the
 //! [struct level documentation](Runtime#shutdown) for more details.
 //!
+//! ## Unix `fork`
+//!
+//! User code that calls `fork(2)` without immediately calling `exec` must not
+//! reuse Tokio in the child process. Tokio supports this kind of fork only in
+//! two cases:
+//!
+//! - The fork happens before the parent process has used Tokio in any way.
+//! - The child process does not use Tokio after the fork.
+//!
+//! Creating or using a Tokio runtime in a child process after the parent has
+//! used Tokio is not supported, even if the runtime in the child is newly
+//! created. Some Tokio modules, including process and signal handling, use
+//! process-global state that cannot currently be reset after `fork`.
+//!
 //! [tasks]: crate::task
 //! [`Runtime`]: Runtime
 //! [`tokio::spawn`]: crate::spawn