Document potential deadlock in extension of WASI, deprecate state_mut

Author: Mark McCaskey

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Changed
 
+- [#1838](https://github.com/wasmerio/wasmer/pull/1838) Deprecate `WasiEnv::state_mut`: prefer `WasiEnv::state` instead.
 - [#1663](https://github.com/wasmerio/wasmer/pull/1663) Function environments passed to host functions now must be passed by `&` instead of `&mut`. This is a breaking change. This change fixes a race condition when a host function is called from multiple threads. If you need mutability in your environment, consider using `std::sync::Mutex` or other synchronization primitives.
 - [#1830](https://github.com/wasmerio/wasmer/pull/1830) Minimum supported Rust version bumped to 1.47.0
 - [#1810](https://github.com/wasmerio/wasmer/pull/1810) Make the `state` field of `WasiEnv` public

lib/wasi/src/lib.rs

@@ -54,6 +54,10 @@ pub enum WasiError {
 pub struct WasiEnv {
     /// Shared state of the WASI system. Manages all the data that the
     /// executing WASI program can see.
+    ///
+    /// Be careful when using this in host functions that call into Wasm:
+    /// if the lock is held and the Wasm calls into a host function that tries
+    /// to lock this mutex, the program will deadlock.
     pub state: Arc<Mutex<WasiState>>,
     memory: Arc<WasiMemory>,
 }
@@ -163,11 +167,17 @@ impl WasiEnv {
     }
 
     /// Get the WASI state
+    ///
+    /// Be careful when using this in host functions that call into Wasm:
+    /// if the lock is held and the Wasm calls into a host function that tries
+    /// to lock this mutex, the program will deadlock.
     pub fn state(&self) -> MutexGuard<WasiState> {
         self.state.lock().unwrap()
     }
 
-    /// Get the WASI state (mutable)
+    // TODO: delete this method before 1.0.0 release
+    #[doc(hidden)]
+    #[deprecated(since = "1.0.0-beta1", note = "Please use the `state` method instead")]
     pub fn state_mut(&mut self) -> MutexGuard<WasiState> {
         self.state.lock().unwrap()
     }