命名 Actor

Actor 在其 namespace 中可以有一个唯一的名称。这允许您从 Ray 集群中的任何作业检索该 Actor。如果您无法直接将 Actor 句柄传递给需要它的任务，或者您正在尝试访问由另一个驱动程序启动的 Actor，这将非常有用。请注意，如果不存在指向该 Actor 的句柄，Actor 仍将被垃圾回收。有关更多详细信息，请参阅 Actor 生命周期。

Python

import ray

@ray.remote
class Counter:
    pass

# Create an actor with a name
counter = Counter.options(name="some_name").remote()

# Retrieve the actor later somewhere
counter = ray.get_actor("some_name")

Java

// Create an actor with a name.
ActorHandle<Counter> counter = Ray.actor(Counter::new).setName("some_name").remote();

...

// Retrieve the actor later somewhere
Optional<ActorHandle<Counter>> counter = Ray.getActor("some_name");
Assert.assertTrue(counter.isPresent());

C++

// Create an actor with a globally unique name
ActorHandle<Counter> counter = ray::Actor(CreateCounter).SetGlobalName("some_name").Remote();

...

// Retrieve the actor later somewhere
boost::optional<ray::ActorHandle<Counter>> counter = ray::GetGlobalActor("some_name");

我们还支持 C++ 中的非全局命名 Actor，这意味着 Actor 名称仅在该作业内有效，并且无法从其他作业访问该 Actor。

// Create an actor with a job-scope-unique name
ActorHandle<Counter> counter = ray::Actor(CreateCounter).SetName("some_name").Remote();

...

// Retrieve the actor later somewhere in the same job
boost::optional<ray::ActorHandle<Counter>> counter = ray::GetActor("some_name");

注意

命名 Actor 按命名空间划分范围。如果未分配命名空间，它们将默认放置在匿名命名空间中。

Python

import ray

@ray.remote
class Actor:
    pass

# driver_1.py
# Job 1 creates an actor, "orange" in the "colors" namespace.
ray.init(address="auto", namespace="colors")
Actor.options(name="orange", lifetime="detached").remote()

# driver_2.py
# Job 2 is now connecting to a different namespace.
ray.init(address="auto", namespace="fruit")
# This fails because "orange" was defined in the "colors" namespace.
ray.get_actor("orange")
# You can also specify the namespace explicitly.
ray.get_actor("orange", namespace="colors")

# driver_3.py
# Job 3 connects to the original "colors" namespace
ray.init(address="auto", namespace="colors")
# This returns the "orange" actor we created in the first job.
ray.get_actor("orange")

Java

import ray

class Actor {
}

// Driver1.java
// Job 1 creates an actor, "orange" in the "colors" namespace.
System.setProperty("ray.job.namespace", "colors");
Ray.init();
Ray.actor(Actor::new).setName("orange").remote();

// Driver2.java
// Job 2 is now connecting to a different namespace.
System.setProperty("ray.job.namespace", "fruits");
Ray.init();
// This fails because "orange" was defined in the "colors" namespace.
Optional<ActorHandle<Actor>> actor = Ray.getActor("orange");
Assert.assertFalse(actor.isPresent());  // actor.isPresent() is false.

// Driver3.java
System.setProperty("ray.job.namespace", "colors");
Ray.init();
// This returns the "orange" actor we created in the first job.
Optional<ActorHandle<Actor>> actor = Ray.getActor("orange");
Assert.assertTrue(actor.isPresent());  // actor.isPresent() is true.

获取或创建命名 Actor

一个常见的用例是仅在 Actor 不存在时才创建它。Ray 为 Actor 创建提供了 get_if_exists 选项，该选项开箱即用地执行此操作。通过 .options() 为 Actor 设置名称后，此方法即可使用。

如果 Actor 已存在，将返回一个指向该 Actor 的句柄，并将忽略参数。否则，将使用指定的参数创建一个新 Actor。

Python

import ray


@ray.remote
class Greeter:
    def __init__(self, value):
        self.value = value

    def say_hello(self):
        return self.value


# Actor `g1` doesn't yet exist, so it is created with the given args.
a = Greeter.options(name="g1", get_if_exists=True).remote("Old Greeting")
assert ray.get(a.say_hello.remote()) == "Old Greeting"

# Actor `g1` already exists, so it is returned (new args are ignored).
b = Greeter.options(name="g1", get_if_exists=True).remote("New Greeting")
assert ray.get(b.say_hello.remote()) == "Old Greeting"

Java

// This feature is not yet available in Java.

C++

// This feature is not yet available in C++.

Actor 生命周期

另外，Actor 的生命周期可以与作业分离，允许 Actor 在作业的驱动程序进程退出后仍然存在。我们将这些 Actor 称为独立的。

Python

counter = Counter.options(name="CounterActor", lifetime="detached").remote()

即使上面脚本运行的驱动程序退出后，CounterActor 也会保持存活。因此，可以在另一个驱动程序中运行以下脚本

counter = ray.get_actor("CounterActor")

请注意，Actor 可以被命名但不能是独立的。如果我们只指定了名称而没有指定 lifetime="detached"，那么只要原始驱动程序仍在运行，就可以检索 CounterActor。

Java

System.setProperty("ray.job.namespace", "lifetime");
Ray.init();
ActorHandle<Counter> counter = Ray.actor(Counter::new).setName("some_name").setLifetime(ActorLifetime.DETACHED).remote();

即使上面进程运行的驱动程序退出后，CounterActor 也会保持存活。因此，可以在另一个驱动程序中运行以下代码

System.setProperty("ray.job.namespace", "lifetime");
Ray.init();
Optional<ActorHandle<Counter>> counter = Ray.getActor("some_name");
Assert.assertTrue(counter.isPresent());

C++

Actor 生命周期的自定义尚未在 C++ 中实现。

与普通 Actor 不同，独立的 Actor 不会被 Ray 自动垃圾回收。一旦确定不再需要独立的 Actor，就必须手动销毁它们。要执行此操作，请使用 ray.kill 手动终止 Actor。在此调用之后，该 Actor 的名称可以被重新使用。