[cleanup] Cleanup docs and other stuff on new thread-local actors

ractor/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ractor"
-version = "0.15.4"
+version = "0.15.5"
 authors = ["Sean Lawlor", "Evan Au", "Dillon George"]
 description = "A actor framework for Rust"
 documentation = "https://docs.rs/ractor"

ractor/src/actor.rs

@@ -73,6 +73,8 @@ pub mod actor_ref;
 pub mod derived_actor;
 mod supervision;
 
+#[cfg(test)]
+mod supervision_tests;
 #[cfg(test)]
 mod tests;
 

ractor/src/actor/tests/supervisor.rs → ractor/src/actor/supervision_tests.rs

@@ -1112,9 +1112,9 @@ async fn test_supervisor_captures_dead_childs_state() {
         }
     }
 
-    let mut temp_state = super::super::messages::BoxedState::new(123u64);
+    let mut temp_state = super::messages::BoxedState::new(123u64);
     assert_eq!(Err(BoxedDowncastErr), temp_state.take::<u32>());
-    let mut temp_state = super::super::messages::BoxedState::new(123u64);
+    let mut temp_state = super::messages::BoxedState::new(123u64);
     assert_eq!(Ok(123u64), temp_state.take::<u64>());
     assert_eq!(Err(BoxedDowncastErr), temp_state.take::<u64>());
 

ractor/src/actor/tests.rs

@@ -21,8 +21,6 @@ use crate::{
     Actor, ActorCell, ActorProcessingErr, ActorRef, ActorStatus, SpawnErr, SupervisionEvent,
 };
 
-mod supervisor;
-
 struct EmptyMessage;
 #[cfg(feature = "cluster")]
 impl crate::Message for EmptyMessage {}

ractor/src/thread_local.rs

@@ -12,7 +12,7 @@
 use std::future::Future;
 
 use crate::concurrency::JoinHandle;
-use crate::Actor as TraditionalActor;
+use crate::Actor as SendActor;
 use crate::ActorCell;
 use crate::ActorName;
 use crate::ActorProcessingErr;
@@ -25,15 +25,10 @@
 
 mod inner;
 #[cfg(test)]
+mod supervision_tests;
+#[cfg(test)]
 mod tests;
 
-/// Represents the state of an thread-local actor. Separate
-/// from the traditional [State] trait, this does NOT require
-/// that the state be [Send] and therefore does NOT need to be
-/// safe to send between threads.
-pub trait ThreadLocalState: std::any::Any + 'static {}
-impl<T: std::any::Any + 'static> ThreadLocalState for T {}
-
 /// [ThreadLocalActor] defines the behavior of an Actor. It specifies the
 /// Message type, State type, and all processing logic for the actor
 ///
@@ -56,13 +51,15 @@
     /// The message type for this actor
     type Msg: Message;
 
-    /// The type of state this actor manages internally
-    type State: ThreadLocalState;
+    /// The type of state this actor manages internally. This type
+    /// has no bound requirements, and needs to neither be [Send] nor
+    /// [Sync] when used in a [ThreadLocalActor] context.
+    type State;
 
     /// Initialization arguments. These must be [Send] as they are
     /// sent to the pinned thread in order to startup the actor.
-    /// However the actor's local `State` does NOT need to be
-    /// [Send] and neither does the actor instance.
+    /// However the actor's local [ThreadLocalActor::State] does
+    /// NOT need to be [Send] and neither does the actor instance.
     type Arguments: State;
 
     /// Invoked when an actor is being started by the system.
@@ -71,14 +68,14 @@
     /// performed here hence why it returns the initial state.
     ///
     /// Panics in `pre_start` do not invoke the
-    /// supervision strategy and the actor won't be started. [Actor]::`spawn`
+    /// supervision strategy and the actor won't be started. [ThreadLocalActor]::`spawn`
     /// will return an error to the caller
     ///
     /// * `myself` - A handle to the [ActorCell] representing this actor
     /// * `args` - Arguments that are passed in the spawning of the actor which might
     ///   be necessary to construct the initial state
     ///
-    /// Returns an initial [Actor::State] to bootstrap the actor
+    /// Returns an initial [ThreadLocalActor::State] to bootstrap the actor
     fn pre_start(
         &self,
         myself: ActorRef<Self::Msg>,
@@ -104,7 +101,7 @@
     }
 
     /// Invoked after an actor has been stopped to perform final cleanup. In the
-    /// event the actor is terminated with [Signal::Kill] or has self-panicked,
+    /// event the actor is terminated with `Signal::Kill` or has self-panicked,
     /// `post_stop` won't be called.
     ///
     /// Panics in `post_stop` follow the supervision strategy.
@@ -183,7 +180,7 @@
     ///
     /// * `name`: A name to give the actor. Useful for global referencing or debug printing
     /// * `handler` The implementation of Self
-    /// * `startup_args`: Arguments passed to the `pre_start` call of the [Actor] to facilitate startup and
+    /// * `startup_args`: Arguments passed to the `pre_start` call of the [ThreadLocalActor] to facilitate startup and
     ///   initial state creation
     ///
     /// Returns a [Ok((ActorRef, JoinHandle<()>))] upon successful start, denoting the actor reference
@@ -200,8 +197,8 @@
     ///
     /// * `name`: A name to give the actor. Useful for global referencing or debug printing
     /// * `handler` The implementation of Self
-    /// * `startup_args`: Arguments passed to the `pre_start` call of the [Actor] to facilitate startup and
-    ///   initial state creation
+    /// * `startup_args`: Arguments passed to the `pre_start` call of the [ThreadLocalActor] to
+    ///   facilitate startup and initial state creation
     /// * `supervisor`: The [ActorCell] which is to become the supervisor (parent) of this actor
     ///
     /// Returns a [Ok((ActorRef, JoinHandle<()>))] upon successful start, denoting the actor reference
@@ -224,26 +221,26 @@
 
 impl<T> ThreadLocalActor for T
 where
-    T: TraditionalActor + Default,
+    T: SendActor + Default,
 {
-    type Msg = <T as TraditionalActor>::Msg;
-    type State = <T as TraditionalActor>::State;
-    type Arguments = <T as TraditionalActor>::Arguments;
+    type Msg = <T as SendActor>::Msg;
+    type State = <T as SendActor>::State;
+    type Arguments = <T as SendActor>::Arguments;
 
     async fn pre_start(
         &self,
         myself: ActorRef<Self::Msg>,
         args: Self::Arguments,
     ) -> Result<Self::State, ActorProcessingErr> {
-        <Self as TraditionalActor>::pre_start(self, myself, args).await
+        <Self as SendActor>::pre_start(self, myself, args).await
     }
 
     async fn post_start(
         &self,
         myself: ActorRef<Self::Msg>,
         state: &mut Self::State,
     ) -> Result<(), ActorProcessingErr> {
-        <Self as TraditionalActor>::post_start(self, myself, state).await
+        <Self as SendActor>::post_start(self, myself, state).await
     }
 
     async fn handle(
@@ -252,7 +249,7 @@
         message: Self::Msg,
         state: &mut Self::State,
     ) -> Result<(), ActorProcessingErr> {
-        <Self as TraditionalActor>::handle(self, myself, message, state).await
+        <Self as SendActor>::handle(self, myself, message, state).await
     }
 
     #[cfg(feature = "cluster")]
@@ -262,7 +259,7 @@
         message: crate::message::SerializedMessage,
         state: &mut Self::State,
     ) -> Result<(), ActorProcessingErr> {
-        <Self as TraditionalActor>::handle_serialized(self, myself, message, state).await
+        <Self as SendActor>::handle_serialized(self, myself, message, state).await
     }
 
     async fn handle_supervisor_evt(
@@ -271,7 +268,7 @@
         message: SupervisionEvent,
         state: &mut Self::State,
     ) -> Result<(), ActorProcessingErr> {
-        <Self as TraditionalActor>::handle_supervisor_evt(self, myself, message, state).await
+        <Self as SendActor>::handle_supervisor_evt(self, myself, message, state).await
     }
 }
 
@@ -282,6 +279,7 @@
             + Send,
     >,
     reply: RpcReplyPort<JoinHandle<Result<JoinHandle<()>, SpawnErr>>>,
+    name: Option<String>,
 }
 
 /// The [ThreadLocalActorSpawner] is responsible for spawning [ThreadLocalActor] instances
@@ -320,10 +318,27 @@
 
             // TODO (seanlawlor): Supported named spawn
             local.spawn_local(async move {
-                while let Some(SpawnArgs { builder, reply }) = recv.recv().await {
+                while let Some(SpawnArgs {
+                    builder,
+                    reply,
+                    name,
+                }) = recv.recv().await
+                {
                     let fut = builder();
-                    let handle = tokio::task::spawn_local(fut);
-                    _ = reply.send(handle);
+                    #[cfg(tokio_unstable)]
+                    {
+                        let mut builder = tokio::task::Builder::new();
+                        if let Some(name) = name {
+                            builder = builder.name(name);
+                        }
+                        builder.spawn_local(fut).expect("Tokio task spawn failed")
+                    }
+                    #[cfg(not(tokio_unstable))]
+                    {
+                        _ = name;
+                        let handle = tokio::task::spawn_local(fut);
+                        _ = reply.send(handle);
+                    }
                 }
                 // If the while loop returns, then all the LocalSpawner
                 // objects have been dropped.
@@ -345,11 +360,13 @@
                     -> std::pin::Pin<Box<dyn Future<Output = Result<JoinHandle<()>, SpawnErr>>>>
                 + Send,
         >,
+        name: Option<String>,
     ) -> Result<JoinHandle<()>, SpawnErr> {
         let (tx, rx) = crate::concurrency::oneshot();
         let args = SpawnArgs {
             builder,
             reply: tx.into(),
+            name,
         };
 
         if self.send.send(args).is_err() {
@@ -362,3 +379,25 @@
             .map_err(|joinerr| SpawnErr::StartupFailed(joinerr.into()))?
     }
 }
+
+impl ActorCell {
+    /// Spawn an actor of the given type as a thread-local child of this actor, automatically starting the actor.
+    /// This [ActorCell] becomes the supervisor of the child actor.
+    ///
+    /// * `name`: A name to give the actor. Useful for global referencing or debug printing
+    /// * `handler` The implementation of Self
+    /// * `startup_args`: Arguments passed to the `pre_start` call of the [Actor] to facilitate startup and
+    ///   initial state creation
+    ///
+    /// Returns a [Ok((ActorRef, JoinHandle<()>))] upon successful start, denoting the actor reference
+    /// along with the join handle which will complete when the actor terminates. Returns [Err(SpawnErr)] if
+    /// the actor failed to start
+    pub async fn spawn_local_linked<T: ThreadLocalActor>(
+        &self,
+        name: Option<String>,
+        startup_args: T::Arguments,
+        spawner: ThreadLocalActorSpawner,
+    ) -> Result<(ActorRef<T::Msg>, JoinHandle<()>), SpawnErr> {
+        T::spawn_linked(name, startup_args, self.clone(), spawner).await
+    }
+}

ractor/src/thread_local/inner.rs

@@ -251,6 +251,7 @@ impl<TActor: ThreadLocalActor> ThreadLocalActorRuntime<TActor> {
         actor_ref.set_status(ActorStatus::Starting);
 
         // Generate the ActorRef which will be returned
+        let spawn_name = name.clone();
         let myself_ret = actor_ref.clone();
 
         // run the processing loop, backgrounding the work
@@ -311,7 +312,7 @@ impl<TActor: ThreadLocalActor> ThreadLocalActorRuntime<TActor> {
             .boxed_local()
         });
         let handle = spawner
-            .spawn(builder)
+            .spawn(builder, spawn_name)
             .await
             .map_err(|e| SpawnErr::StartupFailed(e.into()))?;