doc(socketio): improve documentation for state per client feature

socketioxide/src/adapter.rs

@@ -1,4 +1,4 @@
-//! Adapters are responsible for managing the state of the server.
+//! Adapters are responsible for managing the internal state of the server (rooms, sockets, etc...).
 //! When a socket joins or leaves a room, the adapter is responsible for updating the state.
 //! The default adapter is the [`LocalAdapter`], which stores the state in memory.
 //! Other adapters can be made to share the state between multiple servers.

socketioxide/src/extract/mod.rs

@@ -16,7 +16,7 @@
 //! * [`ProtocolVersion`](crate::ProtocolVersion): extracts the protocol version
 //! * [`TransportType`](crate::TransportType): extracts the transport type
 //! * [`DisconnectReason`](crate::socket::DisconnectReason): extracts the reason of the disconnection
-//! * [`State`]: extracts a reference to a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
+//! * [`State`]: extracts a [`Clone`] of a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
 //! * [`Extension`]: extracts an extension of the given type stored on the called socket by cloning it.
 //! * [`MaybeExtension`]: extracts an extension of the given type if it exists or [`None`] otherwise
 //! * [`HttpExtension`]: extracts an http extension of the given type coming from the request.

socketioxide/src/extract/state.rs

@@ -6,7 +6,7 @@ use crate::adapter::Adapter;
 use crate::handler::{FromConnectParts, FromDisconnectParts, FromMessageParts};
 use crate::socket::{DisconnectReason, Socket};
 
-/// An Extractor that contains a reference to a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
+/// An Extractor that contains a [`Clone`] of a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
 /// It implements [`std::ops::Deref`] to access the inner type so you can use it as a normal reference.
 ///
 /// The specified state type must be the same as the one set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).

socketioxide/src/io.rs

@@ -171,10 +171,11 @@ impl<A: Adapter> SocketIoBuilder<A> {
     /// Add a custom global state for the [`SocketIo`] instance.
     /// This state will be accessible from every handler with the [`State`](crate::extract::State) extractor.
     /// You can set any number of states as long as they have different types.
+    /// The state must be cloneable, therefore it is recommended to wrap it in an `Arc` if you want shared state.
     #[inline]
     #[cfg_attr(docsrs, doc(cfg(feature = "state")))]
     #[cfg(feature = "state")]
-    pub fn with_state<S: Send + Sync + 'static>(self, state: S) -> Self {
+    pub fn with_state<S: Clone + 'static>(self, state: S) -> Self {
         self.state.set(state);
         self
     }

socketioxide/src/lib.rs

@@ -158,7 +158,7 @@
 //! * [`ProtocolVersion`]: extracts the protocol version of the socket
 //! * [`TransportType`]: extracts the transport type of the socket
 //! * [`DisconnectReason`](crate::socket::DisconnectReason): extracts the reason of the disconnection
-//! * [`State`](extract::State): extracts a reference to a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
+//! * [`State`](extract::State): extracts a [`Clone`] of a state previously set with [`SocketIoBuilder::with_state`](crate::io::SocketIoBuilder).
 //! * [`Extension`](extract::Extension): extracts a clone of the corresponding socket extension
 //! * [`MaybeExtension`](extract::MaybeExtension): extracts a clone of the corresponding socket extension if it exists
 //! * [`HttpExtension`](extract::HttpExtension): extracts a clone of the http request extension
@@ -262,12 +262,8 @@
 //! You can enable the `state` feature and use [`SocketIoBuilder::with_state`](SocketIoBuilder) method to set
 //! multiple global states for the server. You can then access them from any handler with the [`State`](extract::State) extractor.
 //!
-//! Because the global state is staticaly defined, beware that the state map will exist for the whole lifetime of the program even
-//! if you drop everything and close you socket.io server. This is a limitation because of the impossibility to have extractors with lifetimes,
-//! therefore state references must be `'static`.
-//!
-//! Another limitation is that because it is common to the whole server. If you build a second server, it will share the same state.
-//! Also if the first server is already started you won't be able to add new states because states are frozen at the start of the first server.
+//! The state is stored in the [`SocketIo`] handle and is shared between all the sockets. The only limitation is that all the provided state types must be clonable.
+//! Therefore it is recommended to use the [`Arc`](std::sync::Arc) type to share the state between the handlers.
 //!
 //! ## Adapters
 //! This library is designed to work with clustering. It uses the [`Adapter`](adapter::Adapter) trait to abstract the underlying storage.