Run handler function in a Tokio LocalSet (#295)

* Run handler function in a Tokio LocalSet

* remove tokio flavor=current_thread from examples

* update changelog

1 files changed, 7 insertions, 5 deletions

diff --git a/azalea/README.md b/azalea/README.md
index 7860741a..3055b0c0 100644
--- a/azalea/README.md
+++ b/azalea/README.md
@@ -42,7 +42,7 @@ use std::sync::Arc;
 use azalea::prelude::*;
 use parking_lot::Mutex;
 
-#[tokio::main(flavor = "current_thread")]
+#[tokio::main]
 async fn main() {
     let account = Account::offline("bot");
     // or Account::microsoft("example@example.com").await.unwrap();
@@ -97,10 +97,6 @@ Also note that just because something is an entity in the ECS doesn't mean that
 
 See the [Bevy Cheatbook](https://bevy-cheatbook.github.io/programming/ecs-intro.html) to learn more about Bevy ECS (and the ECS paradigm in general).
 
-# Using a single-threaded Tokio runtime
-
-Due to the fact that Azalea clients store the ECS in a Mutex that's frequently locked and unlocked, bots that rely on the `Client` or `Swarm` types may run into race condition bugs (like out-of-order events and ticks happening at suboptimal moments) if they do not set Tokio to use a single thread with `#[tokio::main(flavor = "current_thread")]`. This may change in a future version of Azalea. Setting this option will usually not result in a performance hit, and Azalea internally will keep using multiple threads for running the ECS itself (because Tokio is not used for this).
-
 # Debugging
 
 Azalea uses several relatively complex features of Rust, which may make debugging certain issues more tricky if you're not familiar with them.
@@ -121,4 +117,10 @@ If your code is simply hanging, it might be a deadlock. Enable `parking_lot`'s `
 
 Backtraces are also useful, though they're sometimes hard to read and don't always contain the actual location of the error. Run your code with `RUST_BACKTRACE=1` to enable full backtraces. If it's very long, often searching for the keyword "azalea" will help you filter out unrelated things and find the actual source of the issue.
 
+# Other common problems
+
+## Using `tokio::task::spawn_local` instead of `tokio::spawn`
+
+If you spawn a task with `tokio::spawn` and move your bot into it, it's possible for Tokio to run the handler function or schedule a Minecraft tick at an unexpected moment. For instance, `bot.component::<TicksConnected>() == bot.component::<TicksConnected>()` is not guaranteed to be true inside of a `tokio::spawn`. Azalea already mitigates this in the handler function by using a Tokio [LocalSet](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html), but that mitigation does not apply if you call `tokio::spawn` yourself. To avoid this, you must call `tokio::task::spawn_local` in place of `tokio::spawn`. Alternatively, you could also mark your main function with `#[tokio::main(flavor = "current_thread")]`.
+
 [`bevy_log`]: https://docs.rs/bevy_log