From 7c45d1a366ffd8f612bdd1288e516fd6104a0846 Mon Sep 17 00:00:00 2001 From: Qing Wang Date: Wed, 16 Feb 2022 17:57:03 +0800 Subject: [PATCH] [doc][Java] Add doc page for java concurrency group. (#21600) Add document page for Java concurrency group. Co-authored-by: Kai Yang --- doc/source/ray-core/concurrency_group_api.rst | 114 ++++++++++++++++-- 1 file changed, 103 insertions(+), 11 deletions(-) diff --git a/doc/source/ray-core/concurrency_group_api.rst b/doc/source/ray-core/concurrency_group_api.rst index a8d6c152a..674fd277c 100644 --- a/doc/source/ray-core/concurrency_group_api.rst +++ b/doc/source/ray-core/concurrency_group_api.rst @@ -10,15 +10,16 @@ Besides setting the max concurrency overall for an asyncio actor, Ray allows met Defining Concurrency Groups --------------------------- -You can define concurrency groups for asyncio actors using the ``concurrency_groups`` decorator argument: +This defines two concurrency groups, "io" with max concurrency = 2 and +"compute" with max concurrency = 4. The methods ``f1`` and ``f2`` are +placed in the "io" group, and the methods ``f3`` and ``f4`` are placed +into the "compute" group. Note that there is always a default +concurrency group, which has a default concurrency of 1000 in Python and +1 in Java. .. tabbed:: Python - This defines two concurrency groups, "io" with max_concurrency=2 and - "compute" with max_concurrency=4. The methods ``f1`` and ``f2`` are - placed in the "io" group, and the methods ``f3`` and ``f4`` are placed - into the "compute" group. Note that there is always a default - concurrency group, which has a default concurrency of 1000. + You can define concurrency groups for asyncio actors using the ``concurrency_group`` decorator argument: .. code-block:: python @@ -53,13 +54,66 @@ You can define concurrency groups for asyncio actors using the ``concurrency_gro a.f4.remote() # executed in the "compute" group. a.f5.remote() # executed in the default group. +.. tabbed:: Java + + You can define concurrency groups for concurrent actors using the API ``setConcurrencyGroups()`` argument: + + .. code-block:: java + + class ConcurrentActor { + public long f1() { + return Thread.currentThread().getId(); + } + + public long f2() { + return Thread.currentThread().getId(); + } + + public long f3(int a, int b) { + return Thread.currentThread().getId(); + } + + public long f4() { + return Thread.currentThread().getId(); + } + + public long f5() { + return Thread.currentThread().getId(); + } + } + + ConcurrencyGroup group1 = + new ConcurrencyGroupBuilder() + .setName("io") + .setMaxConcurrency(1) + .addMethod(ConcurrentActor::f1) + .addMethod(ConcurrentActor::f2) + .build(); + ConcurrencyGroup group2 = + new ConcurrencyGroupBuilder() + .setName("compute") + .setMaxConcurrency(1) + .addMethod(ConcurrentActor::f3) + .addMethod(ConcurrentActor::f4) + .build(); + + ActorHandle myActor = Ray.actor(ConcurrentActor::new) + .setConcurrencyGroups(group1, group2) + .remote(); + + myActor.task(ConcurrentActor::f1).remote(); // executed in the "io" group. + myActor.task(ConcurrentActor::f2).remote(); // executed in the "io" group. + myActor.task(ConcurrentActor::f3, 3, 5).remote(); // executed in the "compute" group. + myActor.task(ConcurrentActor::f4).remote(); // executed in the "compute" group. + myActor.task(ConcurrentActor::f5).remote(); // executed in the "default" group. + .. _default-concurrency-group: Default Concurrency Group ------------------------- -By default, methods are placed in a default concurrency group which has a concurrency limit of 1000. +By default, methods are placed in a default concurrency group which has a concurrency limit of 1000 in Python, 1 in Java. The concurrency of the default group can be changed by setting the ``max_concurrency`` actor option. .. tabbed:: Python @@ -76,18 +130,44 @@ The concurrency of the default group can be changed by setting the ``max_concurr actor = AsyncIOActor.options(max_concurrency=10).remote() +.. tabbed:: Java + + The following concurrent actor has 2 concurrency groups: "io" and "default". + The max concurrency of "io" is 2, and the max concurrency of "default" is 10. + + .. code-block:: java + + class ConcurrentActor: + public long f1() { + return Thread.currentThread().getId(); + } + + ConcurrencyGroup group = + new ConcurrencyGroupBuilder() + .setName("io") + .setMaxConcurrency(2) + .addMethod(ConcurrentActor::f1) + .build(); + + ActorHandle myActor = Ray.actor(ConcurrentActor::new) + .setConcurrencyGroups(group1) + .setMaxConcurrency(10) + .remote(); + .. _setting-the-concurrency-group-at-runtime: Setting the Concurrency Group at Runtime ---------------------------------------- -You can also dispatch actor methods into a specific concurrency group at runtime using the ``.options`` method: +You can also dispatch actor methods into a specific concurrency group at runtime. + +The following snippet demonstrates setting the concurrency group of the +``f2`` method dynamically at runtime. .. tabbed:: Python - - The following snippet demonstrates setting the concurrency group of the - ``f2`` method dynamically at runtime. + + You can use the ``.options`` method. .. code-block:: python @@ -96,3 +176,15 @@ You can also dispatch actor methods into a specific concurrency group at runtime # Executed in the "compute" group. a.f2.options(concurrency_group="compute").remote() + +.. tabbed:: Java + + You can use ``setConcurrencyGroup`` method. + + .. code-block:: java + + // Executed in the "io" group (as defined in the actor creation). + myActor.task(ConcurrentActor::f2).remote(); + + // Executed in the "compute" group. + myActor.task(ConcurrentActor::f2).setConcurrencyGroup("compute").remote();