[Core] Enhance docs of options (ray-project#26773)

* enhance docs

Signed-off-by: Siyuan Zhuang <[email protected]>

python/ray/actor.py

@@ -534,6 +534,73 @@ def options(self, **actor_options):
  The arguments are the same as those that can be passed
  to :obj:`ray.remote`.
 
+ Args:
+ num_cpus: The quantity of CPU cores to reserve
+ for this task or for the lifetime of the actor.
+ num_gpus: The quantity of GPUs to reserve
+ for this task or for the lifetime of the actor.
+ resources (Dict[str, float]): The quantity of various custom resources
+ to reserve for this task or for the lifetime of the actor.
+ This is a dictionary mapping strings (resource names) to floats.
+ accelerator_type: If specified, requires that the task or actor run
+ on a node with the specified type of accelerator.
+ See `ray.accelerators` for accelerator types.
+ memory: The heap memory request for this task/actor.
+ object_store_memory: The object store memory request for actors only.
+ max_restarts: This specifies the maximum
+ number of times that the actor should be restarted when it dies
+ unexpectedly. The minimum valid value is 0 (default),
+ which indicates that the actor doesn't need to be restarted.
+ A value of -1 indicates that an actor should be restarted
+ indefinitely.
+ max_task_retries: How many times to
+ retry an actor task if the task fails due to a system error,
+ e.g., the actor has died. If set to -1, the system will
+ retry the failed task until the task succeeds, or the actor
+ has reached its max_restarts limit. If set to `n > 0`, the
+ system will retry the failed task up to n times, after which the
+ task will throw a `RayActorError` exception upon :obj:`ray.get`.
+ Note that Python exceptions are not considered system errors
+ and will not trigger retries.
+ max_pending_calls: Set the max number of pending calls
+ allowed on the actor handle. When this value is exceeded,
+ PendingCallsLimitExceeded will be raised for further tasks.
+ Note that this limit is counted per handle. -1 means that the
+ number of pending calls is unlimited.
+ max_concurrency: The max number of concurrent calls to allow for
+ this actor. This only works with direct actor calls. The max
+ 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, which can be used
+ to retrieve the actor via ray.get_actor(name) as long as the
+ actor is still alive.
+ namespace: Override the namespace to use for the actor. By default,
+ actors are created in an anonymous namespace. The actor can
+ be retrieved via ray.get_actor(name=name, namespace=namespace).
+ 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.
+ runtime_env (Dict[str, Any]): Specifies the runtime environment for
+ this actor or task and its children. See
+ :ref:`runtime-environments` for detailed documentation. This API is
+ in beta and may change before becoming stable.
+ scheduling_strategy: Strategy about how to
+ schedule a remote function or actor. Possible values are
+ None: ray will figure out the scheduling strategy to use, it
+ will either be the PlacementGroupSchedulingStrategy using parent's
+ placement group if parent has one and has
+ placement_group_capture_child_tasks set to true,
+ or "DEFAULT";
+ "DEFAULT": default hybrid scheduling;
+ "SPREAD": best effort spread scheduling;
+ `PlacementGroupSchedulingStrategy`:
+ placement group based scheduling.
+ _metadata: Extended options for Ray libraries. For example,
+ _metadata={"workflows.io/options": <workflow options>} for
+ Ray workflows.
+
  Examples:
 
  .. code-block:: python
@@ -542,7 +609,7 @@ def options(self, **actor_options):
  class Foo:
  def method(self):
  return 1
- # Class Foo will require 1 cpu instead of 2.
+ # Class Bar will require 1 cpu instead of 2.
  # It will also require no custom resources.
  Bar = Foo.options(num_cpus=1, resources=None)
  """

python/ray/remote_function.py

@@ -135,14 +135,62 @@ def options(self, **task_options):
  The arguments are the same as those that can be passed to :obj:`ray.remote`.
  Overriding `max_calls` is not supported.
 
+ Args:
+ num_returns: It specifies the number of object refs returned by
+ the remote function invocation.
+ num_cpus: The quantity of CPU cores to reserve
+ for this task or for the lifetime of the actor.
+ num_gpus: The quantity of GPUs to reserve
+ for this task or for the lifetime of the actor.
+ resources (Dict[str, float]): The quantity of various custom resources
+ to reserve for this task or for the lifetime of the actor.
+ This is a dictionary mapping strings (resource names) to floats.
+ accelerator_type: If specified, requires that the task or actor run
+ on a node with the specified type of accelerator.
+ See `ray.accelerators` for accelerator types.
+ memory: The heap memory request for this task/actor.
+ object_store_memory: The object store memory request for actors only.
+ max_calls: This specifies the
+ maximum number of times that a given worker can execute
+ the given remote function before it must exit
+ (this can be used to address memory leaks in third-party
+ libraries or to reclaim resources that cannot easily be
+ released, e.g., GPU memory that was acquired by TensorFlow).
+ By default this is infinite.
+ max_retries: This specifies the maximum number of times that the remote
+ function should be rerun when the worker process executing it
+ crashes unexpectedly. The minimum valid value is 0,
+ the default is 4 (default), and a value of -1 indicates
+ infinite retries.
+ runtime_env (Dict[str, Any]): Specifies the runtime environment for
+ this actor or task and its children. See
+ :ref:`runtime-environments` for detailed documentation. This API is
+ in beta and may change before becoming stable.
+ retry_exceptions: This specifies whether application-level errors
+ should be retried up to max_retries times.
+ scheduling_strategy: Strategy about how to
+ schedule a remote function or actor. Possible values are
+ None: ray will figure out the scheduling strategy to use, it
+ will either be the PlacementGroupSchedulingStrategy using parent's
+ placement group if parent has one and has
+ placement_group_capture_child_tasks set to true,
+ or "DEFAULT";
+ "DEFAULT": default hybrid scheduling;
+ "SPREAD": best effort spread scheduling;
+ `PlacementGroupSchedulingStrategy`:
+ placement group based scheduling.
+ _metadata: Extended options for Ray libraries. For example,
+ _metadata={"workflows.io/options": <workflow options>} for
+ Ray workflows.
+
  Examples:
 
  .. code-block:: python
 
  @ray.remote(num_gpus=1, max_calls=1, num_returns=2)
  def f():
  return 1, 2
- # Task f will require 2 gpus instead of 1.
+ # Task g will require 2 gpus instead of 1.
  g = f.options(num_gpus=2)
  """