[api] Clean up and document Actor name / lifetime API (#10332)

python/ray/actor.py

@@ -411,7 +411,7 @@ class ActorClass:
                 max_restarts=None,
                 max_task_retries=None,
                 name=None,
-                detached=False,
+                lifetime=None,
                 placement_group=None,
                 placement_group_bundle_index=-1):
         """Create an actor.
@@ -436,8 +436,13 @@ class ActorClass:
                 concurrency defaults to 1 for threaded execution, and 1000 for
                 asyncio execution. Note that the execution order is not
                 guaranteed when max_concurrency > 1.
-            name: The globally unique name for the actor.
-            detached: DEPRECATED.
+            name: The globally unique name for the actor, which can be used
+                to retrieve the actor via ray.get_actor(name) as long as the
+                actor is still alive.
+            lifetime: Either `None`, which defaults to the actor will fate
+                share with its creator and will be deleted once its refcount
+                drops to zero, or "detached", which means the actor will live
+                as a global object independent of the creator.
             placement_group: the placement group this actor belongs to,
                 or None if it doesn't belong to any group.
             placement_group_bundle_index: the index of the bundle
@@ -472,10 +477,6 @@ class ActorClass:
         worker = ray.worker.global_worker
         worker.check_connected()
 
-        if detached:
-            logger.warning("The detached flag is deprecated. To create a "
-                           "detached actor, use the name parameter.")
-
         if name is not None:
             if not isinstance(name, str):
                 raise TypeError(
@@ -498,9 +499,13 @@ class ActorClass:
                     f"The name {name} is already taken. Please use "
                     "a different name or get the existing actor using "
                     f"ray.get_actor('{name}')")
+
+        if lifetime is None:
+            detached = False
+        elif lifetime == "detached":
             detached = True
         else:
-            detached = False
+            raise ValueError("lifetime must be either `None` or 'detached'")
 
         if placement_group is None:
             placement_group = PlacementGroup.empty()