[core/docs] Update worker docstring (ray-project#28495)

Co-authored-by: Philipp Moritz <[email protected]>

doc/source/ray-core/tips-for-first-time.rst

@@ -45,6 +45,7 @@ Since each task requests by default one CPU, this setting allows us to execute u
 As a result, our Ray system consists of one driver executing the program,
 and up to four workers running remote tasks or actors.
 
+.. _tip-delay-get:
 
 Tip 1: Delay ray.get()
 ----------------------

python/ray/_private/worker.py

@@ -55,6 +55,7 @@
 import ray._private.storage as storage
 
 # Ray modules
+import ray.actor
 import ray.cloudpickle as pickle
 import ray.job_config
 import ray.remote_function
@@ -2587,6 +2588,9 @@ def _mode(worker=global_worker):
 
 
 def _make_remote(function_or_class, options):
+    if not function_or_class.__module__:
+        function_or_class.__module__ = "global"
+
     if inspect.isfunction(function_or_class) or is_cython(function_or_class):
         ray_option_utils.validate_task_options(options, in_options=False)
         return ray.remote_function.RemoteFunction(
@@ -2777,57 +2781,110 @@ def remote(
 
 
 @PublicAPI
-def remote(*args, **kwargs):
+def remote(
+    *args, **kwargs
+) -> Union[ray.remote_function.RemoteFunction, ray.actor.ActorClass]:
     """Defines a remote function or an actor class.
 
-    This can be used with no arguments to define a remote function or actor as
-    follows:
-
-    .. code-block:: python
-
-        @ray.remote
-        def f():
-            return 1
+    This function can be used as a decorator with no arguments
+    to define a remote function or actor as follows:
+
+    >>> import ray
+    >>>
+    >>> @ray.remote
+    ... def f(a, b, c):
+    ...     return a + b + c
+    >>>
+    >>> object_ref = f.remote(1, 2, 3)
+    >>> result = ray.get(object_ref)
+    >>> assert result == (1 + 2 + 3)
+    >>>
+    >>> @ray.remote
+    ... class Foo:
+    ...     def __init__(self, arg):
+    ...         self.x = arg
+    ...
+    ...     def method(self, a):
+    ...         return self.x + a
+    >>>
+    >>> actor_handle = Foo.remote(123)
+    >>> object_ref = actor_handle.method.remote(321)
+    >>> result = ray.get(object_ref)
+    >>> assert result == (123 + 321)
+
+    Equivalently, use a function call to create a remote function or actor.
+
+    >>> def g(a, b, c):
+    ...     return a + b + c
+    >>>
+    >>> remote_g = ray.remote(g)
+    >>> object_ref = remote_g.remote(1, 2, 3)
+    >>> assert ray.get(object_ref) == (1 + 2 + 3)
+
+    >>> class Bar:
+    ...     def __init__(self, arg):
+    ...         self.x = arg
+    ...
+    ...     def method(self, a):
+    ...         return self.x + a
+    >>>
+    >>> RemoteBar = ray.remote(Bar)
+    >>> actor_handle = RemoteBar.remote(123)
+    >>> object_ref = actor_handle.method.remote(321)
+    >>> result = ray.get(object_ref)
+    >>> assert result == (123 + 321)
 
-        @ray.remote
-        class Foo:
-            def method(self):
-                return 1
 
     It can also be used with specific keyword arguments as follows:
 
-    .. code-block:: python
-
-        @ray.remote(num_gpus=1, max_calls=1, num_returns=2)
-        def f():
-            return 1, 2
-
-        @ray.remote(num_cpus=2, resources={"CustomResource": 1})
-        class Foo:
-            def method(self):
-                return 1
+    >>> @ray.remote(num_gpus=1, max_calls=1, num_returns=2)
+    ... def f():
+    ...     return 1, 2
+    >>>
+    >>> @ray.remote(num_cpus=2, resources={"CustomResource": 1})
+    ... class Foo:
+    ...     def method(self):
+    ...         return 1
 
     Remote task and actor objects returned by @ray.remote can also be
     dynamically modified with the same arguments as above using
     ``.options()`` as follows:
 
-    .. code-block:: python
+    >>> @ray.remote(num_gpus=1, max_calls=1, num_returns=2)
+    ... def f():
+    ...     return 1, 2
+    >>>
+    >>> f_with_2_gpus = f.options(num_gpus=2) # doctest: +SKIP
+    >>> object_ref = f_with_2_gpus.remote() # doctest: +SKIP
+    >>> assert ray.get(object_ref) == (1, 2) # doctest: +SKIP
+
+    >>> @ray.remote(num_cpus=2, resources={"CustomResource": 1})
+    ... class Foo:
+    ...     def method(self):
+    ...         return 1
+    >>>
+    >>> Foo_with_no_resources = Foo.options(num_cpus=1, resources=None)
+    >>> foo_actor = Foo_with_no_resources.remote()
+    >>> assert ray.get(foo_actor.method.remote()) == 1
+
+
+    A remote actor will be terminated when all actor handle to it
+    in Python is deleted, which will cause them to complete any outstanding
+    work and then shut down. If you only have 1 reference to an actor handle,
+    calling ``del actor`` *could* trigger actor deletion. Note that your program
+    may have multiple references to the same ActorHandle, and actor termination
+    will not occur until the reference count goes to 0. See the Python
+    documentation for more context about object deletion.
+    https://docs.python.org/3.9/reference/datamodel.html#object.__del__
 
-        @ray.remote(num_gpus=1, max_calls=1, num_returns=2)
-        def f():
-            return 1, 2
-        g = f.options(num_gpus=2)
+    If you want to kill actors immediately, you can also call ``ray.kill(actor)``.
 
-        @ray.remote(num_cpus=2, resources={"CustomResource": 1})
-        class Foo:
-            def method(self):
-                return 1
-        Bar = Foo.options(num_cpus=1, resources=None)
+    .. tip::
+        Avoid repeatedly passing in large arguments to remote task or method calls.
 
-    Running remote actors will be terminated when the actor handle to them
-    in Python is deleted, which will cause them to complete any outstanding
-    work and then shut down. If you want to kill them immediately, you can
-    also call ``ray.kill(actor)``.
+        Instead, use ray.put to create a copy of the object in the object store.
+
+        See :ref:`more info here <tip-delay-get>`.
 
     Args:
         num_returns: This is only for *remote functions*. It specifies
@@ -2892,6 +2949,7 @@ def method(self):
             placement group based scheduling.
         _metadata: Extended options for Ray libraries. For example,
             _metadata={"workflows.io/options": <workflow options>} for Ray workflows.
+
     """
     # "callable" returns true for both function and class.
     if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):

python/ray/runtime_context.py

@@ -36,7 +36,7 @@ def get(self) -> Dict[str, Any]:
 
         return context
 
-    @Deprecated(message="Use get_job_id() instead")
+    @Deprecated(message="Use get_job_id() instead.")
     @property
     def job_id(self):
         """Get current job ID for this worker or driver.
@@ -45,7 +45,8 @@ def job_id(self):
 
         Returns:
             If called by a driver, this returns the job ID. If called in
-                a task, return the job ID of the associated driver.
+            a task, return the job ID of the associated driver.
+
         """
         job_id = self.worker.current_job_id
         assert not job_id.is_nil()
@@ -58,22 +59,22 @@ def get_job_id(self) -> str:
 
         Returns:
             If called by a driver, this returns the job ID. If called in
-                a task, return the job ID of the associated driver. The
-                job ID will be hex format.
+            a task, return the job ID of the associated driver. The
+            job ID will be hex format.
         """
         job_id = self.worker.current_job_id
         assert not job_id.is_nil()
         return job_id.hex()
 
-    @Deprecated(message="Use get_node_id() instead")
+    @Deprecated(message="Use get_node_id() instead.")
     @property
     def node_id(self):
         """Get current node ID for this worker or driver.
 
         Node ID is the id of a node that your driver, task, or actor runs.
 
         Returns:
-            a node id for this worker or driver.
+            A node id for this worker or driver.
         """
         node_id = self.worker.current_node_id
         assert not node_id.is_nil()

python/ray/util/actor_pool.py

@@ -1,7 +1,7 @@
 from typing import List, Callable, Any
 
 import ray
-from ray.util.annotations import Deprecated, PublicAPI
+from ray.util.annotations import Deprecated
 from ray._private.utils import get_ray_doc_version
 
 
@@ -12,7 +12,6 @@
     "Datasets.map_batches(compute=ActorPoolStrategy, ...), see details in "
     f"https://docs.ray.io/en/{get_ray_doc_version()}/data/api/dataset.html#ray.data.Dataset.map_batches."  # noqa: E501
 )
-@PublicAPI(stability="beta")
 class ActorPool:
     """Utility class to operate on a fixed pool of actors.