Document issue with shutdown

README.md

@@ -131,3 +131,28 @@ For instance:
 - `RUST_LOG=zenoh=debug` activates all the debug logs.
 
 For more information on the `RUST_LOG` syntax, see https://docs.rs/env_logger/latest/env_logger/#enabling-logging.
+
+### Known Issues
+
+### Crash when program terminates
+
+When a program terminates, global and static objects are destructed in the reverse order of their
+construction.
+The `Thread Local Storage` is one such entity which the `tokio` runtime in Zenoh uses.
+If the Zenoh session is closed after this entity is cleared, it causes a panic like seen below.
+
+```
+thread '<unnamed>' panicked at /rustc/aedd173a2c086e558c2b66d3743b344f977621a7/library/std/src/thread/local.rs:262:26:
+cannot access a Thread Local Storage value during or after destruction: AccessError
+```
+
+This can happen with `rmw_zenoh` if the ROS 2 `Context` is not shutdown explicitly before the
+program terminates.
+In this scenario, the `Context` will be shutdown inside the `Context`'s destructor which then closes the Zenoh session.
+Since the ordering of global/static objects is not defined, this often leads to the above panic.
+
+The recommendation is to ensure the `Context` is shutdown before a program terminates.
+One way to ensure this is to call `rclcpp::shutdown()` when the program exits.
+Note that composable nodes should *never* call `rclcpp::shutdown()`, as the composable node container will automatically do this.
+
+For more details, see https://github.com/ros2/rmw_zenoh/issues/170.