Repository: slawlor/ractor
Pull request #18 (2023-01-10 17:36:12)

Documentation update associated with v0.3 release


Patch:
diff --git a/README.md b/README.md
index 0fb1072..3033124 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # ractor
 
+*Pronounced **R**-aktor*
+
 A pure-Rust actor framework. Inspired from [Erlang's `gen_server`](https://www.erlang.org/doc/man/gen_server.html), with the speed + performance of Rust!
 
 [<img alt="github" src="https://img.shields.io/badge/github-slawlor/ractor-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/slawlor/ractor)
@@ -29,6 +31,8 @@ We currently have full support for
 2. Actor supervision tree
 3. Remote procedure calls to actors
 4. Timers
+5. Named actor registry (`ractor::registry`) from [Erlang's `Registered processes`](https://www.erlang.org/doc/reference_manual/processes.html)
+6. Process groups (`ractor::pg`) from [Erlang's `pg` module](https://www.erlang.org/doc/man/pg.html)
 
 
 On our roadmap is to add more of the Erlang functionality including potentially a distributed actor cluster.
@@ -39,7 +43,7 @@ Install `ractor` by adding the following to your Cargo.toml dependencies
 
 ```toml
 [dependencies]
-ractor = "0.1"
+ractor = "0.3"
 ```
 
 ## Working with Actors
@@ -104,16 +108,15 @@ impl ActorHandler for PingPong {
         &self,
         myself: ActorCell,
         message: Self::Msg,
-        state: &Self::State,
-    ) -> Option<Self::State> {
+        state: &mut Self::State,
+    ){
         if *state < 10u8 {
             message.print();
             self.send_message(myself, message.next()).unwrap();
-            Some(*state + 1)
+            *state += 1;
         } else {
             myself.stop(None);
             // don't send another message, rather stop the agent after 10 iterations
-            None
         }
     }
 }
diff --git a/ractor/Cargo.toml b/ractor/Cargo.toml
index 822b1d5..63ec90e 100644
--- a/ractor/Cargo.toml
+++ b/ractor/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ractor"
-version = "0.3.0"
+version = "0.3.1"
 authors = ["Sean Lawlor", "Evan Au", "Dillon George"]
 description = "A actor framework for Rust"
 documentation = "https://docs.rs/ractor"
diff --git a/ractor/src/actor/actor_cell/actor_ref.rs b/ractor/src/actor/actor_cell/actor_ref.rs
index 3f9f902..5339c21 100644
--- a/ractor/src/actor/actor_cell/actor_ref.rs
+++ b/ractor/src/actor/actor_cell/actor_ref.rs
@@ -107,9 +107,9 @@ where
 
     /// Try and retrieve a strongly-typed actor from the registry.
     ///
-    /// Alias of [crate::registry::try_get]
-    pub fn try_get_from_registry(name: ActorName) -> Option<ActorRef<TActor>> {
-        if let Some(actor) = crate::registry::try_get(name) {
+    /// Alias of [crate::registry::where_is]
+    pub fn where_is(name: ActorName) -> Option<ActorRef<TActor>> {
+        if let Some(actor) = crate::registry::where_is(name) {
             // check the type id when pulling from the registry
             if actor.inner.type_id == TypeId::of::<TActor>() {
                 Some(actor.into())
diff --git a/ractor/src/actor/actor_cell/mod.rs b/ractor/src/actor/actor_cell/mod.rs
index e4f3d7c..96e99f0 100644
--- a/ractor/src/actor/actor_cell/mod.rs
+++ b/ractor/src/actor/actor_cell/mod.rs
@@ -163,7 +163,7 @@ impl ActorCell {
             inner: Arc::new(props),
         };
         if let Some(r_name) = name {
-            crate::registry::enroll(r_name, cell.clone())?;
+            crate::registry::register(r_name, cell.clone())?;
         }
 
         Ok((
@@ -205,7 +205,7 @@ impl ActorCell {
         if status == ActorStatus::Stopped || status == ActorStatus::Stopping {
             // If it's enrolled in the registry, remove it
             if let Some(name) = self.get_name() {
-                crate::registry::unenroll(name);
+                crate::registry::unregister(name);
             }
             // Leave all + stop monitoring pg groups (if any)
             crate::pg::demonitor_all(self.get_id());
diff --git a/ractor/src/registry/mod.rs b/ractor/src/registry/mod.rs
index 5c291ac..ebfa8eb 100644
--- a/ractor/src/registry/mod.rs
+++ b/ractor/src/registry/mod.rs
@@ -13,7 +13,7 @@
 //! automatically unenrolled from the registry upon being dropped, therefore freeing
 //! the name for subsequent registration.
 //!
-//! You can then retrieve actors by name with [try_get]. Note: this
+//! You can then retrieve actors by name with [where_is]. Note: this
 //! function only returns the [ActorCell] reference to the actor, it
 //! additionally requires knowledge of the [crate::ActorHandler] in order
 //! to send messages to it (since you need to know the message type)
@@ -24,7 +24,7 @@
 //!
 //! ```rust
 //! async fn test() {
-//!     let maybe_actor = ractor::registry::try_get("my_actor");
+//!     let maybe_actor = ractor::registry::where_is("my_actor");
 //!     if let Some(actor) = maybe_actor {
 //!         // send a message, or interact with the actor
 //!         // but you'll need to know the actor's strong type
@@ -58,7 +58,7 @@ fn get_actor_registry<'a>() -> &'a Arc<DashMap<ActorName, ActorCell>> {
 }
 
 /// Put an actor into the registry
-pub(crate) fn enroll(name: ActorName, actor: ActorCell) -> Result<(), ActorRegistryErr> {
+pub(crate) fn register(name: ActorName, actor: ActorCell) -> Result<(), ActorRegistryErr> {
     match get_actor_registry().entry(name) {
         Occupied(_) => Err(ActorRegistryErr::AlreadyRegistered(name)),
         Vacant(vacancy) => {
@@ -69,7 +69,7 @@ pub(crate) fn enroll(name: ActorName, actor: ActorCell) -> Result<(), ActorRegis
 }
 
 /// Remove an actor from the registry given it's actor name
-pub(crate) fn unenroll(name: ActorName) {
+pub(crate) fn unregister(name: ActorName) {
     if let Some(reg) = ACTOR_REGISTRY.get() {
         let _ = reg.remove(&name);
     }
@@ -81,7 +81,16 @@ pub(crate) fn unenroll(name: ActorName) {
 ///
 /// Returns: Some(actor) on successful identification of an actor, None if
 /// actor not registered
-pub fn try_get(name: ActorName) -> Option<ActorCell> {
+pub fn where_is(name: ActorName) -> Option<ActorCell> {
     let reg = get_actor_registry();
     reg.get(&name).map(|v| v.value().clone())
 }
+
+/// Returns a list of names that have been registered
+///
+/// Returns: A [Vec<&'str>] of actor names which are registered
+/// currently
+pub fn registered() -> Vec<ActorName> {
+    let reg = get_actor_registry();
+    reg.iter().map(|kvp| *kvp.key()).collect::<Vec<_>>()
+}


Test patch:
diff --git a/ractor/src/registry/tests.rs b/ractor/src/registry/tests.rs
index eb240cb..4c03600 100644
--- a/ractor/src/registry/tests.rs
+++ b/ractor/src/registry/tests.rs
@@ -26,7 +26,7 @@ async fn test_basic_registation() {
         .await
         .expect("Actor failed to start");
 
-    assert!(crate::registry::try_get("my_actor").is_some());
+    assert!(crate::registry::where_is("my_actor").is_some());
 
     actor.stop(None);
     handle.await.expect("Failed to clean stop the actor");
@@ -49,7 +49,7 @@ async fn test_duplicate_registration() {
         .await
         .expect("Actor failed to start");
 
-    assert!(crate::registry::try_get("my_second_actor").is_some());
+    assert!(crate::registry::where_is("my_second_actor").is_some());
 
     let second_actor = Actor::spawn(Some("my_second_actor"), EmptyActor).await;
     // fails to spawn the second actor due to name err
@@ -59,7 +59,7 @@ async fn test_duplicate_registration() {
     ));
 
     // make sure the first actor is still registered
-    assert!(crate::registry::try_get("my_second_actor").is_some());
+    assert!(crate::registry::where_is("my_second_actor").is_some());
 
     actor.stop(None);
     handle.await.expect("Failed to clean stop the actor");
@@ -82,7 +82,7 @@ async fn test_actor_registry_unenrollment() {
         .await
         .expect("Actor failed to start");
 
-    assert!(crate::registry::try_get("unenrollment").is_some());
+    assert!(crate::registry::where_is("unenrollment").is_some());
 
     // stop the actor and wait for its death
     actor.stop(None);
@@ -95,5 +95,5 @@ async fn test_actor_registry_unenrollment() {
     tokio::time::sleep(Duration::from_millis(100)).await;
 
     // the actor was automatically removed
-    assert!(crate::registry::try_get("unenrollment").is_none());
+    assert!(crate::registry::where_is("unenrollment").is_none());
 }