Documentation of Runtime::enter features unfortunate, slightly nondeterministic, and thus quite confusing example

[steffahn]

The bad user experience is demonstrated in this question thread on URLO. The underlying problem is that the user got the example code from Runtime::enter docs

use tokio::runtime::Runtime;

fn function_that_spawns(msg: String) {
    // Had we not used `rt.enter` below, this would panic.
    tokio::spawn(async move {
        println!("{}", msg);
    });
}

fn main() {
    let rt = Runtime::new().unwrap();

    let s = "Hello World!".to_string();

    // By entering the context, we tie `tokio::spawn` to this executor.
    let _guard = rt.enter();
    function_that_spawns(s);
}

and then tried out modifications to see how they behave. The problem is that this code turns out to print “Hello World” quite likely, but not necessarily, whereas other modified versions of it might have other random tendencies; before a user discovers the nondeterminism, this can cause lots of confusion.

In my opinion, the example at least needs updating that clearly calls out the non-determined nature of this example program’s behavior. Furthermore, I would appreciate a more natural example that doesn’t feature such randomness at all… though off the top of my head, I’m not sure what the most idiomatic use-case of Runtime::enter is in the first place, since avoiding premature cancellation of spawned tasks usually involves using Runtime::block_on and once you use Runtime::block_on, you don’t really need explicit Runtime::enter anymore…

---

I’m not sure if “bug” or “feature-request” is the correct category for documentation issues.

[Darksonn]

Thank you for reporting this. Documentation bugs are definitely bugs.