Using Namespaces

A namespace is a logical grouping of jobs and named actors. When an actor is named, its name must be unique within the namespace.

In order to set your applications namespace, it should be specified when you first connect to the cluster.

Python

import ray

ray.init(namespace="hello")

Java

System.setProperty("ray.job.namespace", "hello"); // set it before Ray.init()
Ray.init();

C++

ray::RayConfig config;
config.ray_namespace = "hello";
ray::Init(config);

Please refer to Driver Options for ways of configuring a Java application.

Named actors are only accessible within their namespaces.

Python

import subprocess
import ray

try:
    subprocess.check_output(["ray", "start", "--head"])

    @ray.remote
    class Actor:
      pass

    # Job 1 creates two actors, "orange" and "purple" in the "colors" namespace.
    with ray.init("ray://localhost:10001", namespace="colors"):
      Actor.options(name="orange", lifetime="detached").remote()
      Actor.options(name="purple", lifetime="detached").remote()

    # Job 2 is now connecting to a different namespace.
    with ray.init("ray://localhost:10001", namespace="fruits"):
      # This fails because "orange" was defined in the "colors" namespace.
      try:
        ray.get_actor("orange")
      except ValueError:
        pass

      # This succceeds because the name "orange" is unused in this namespace.
      Actor.options(name="orange", lifetime="detached").remote()
      Actor.options(name="watermelon", lifetime="detached").remote()

    # Job 3 connects to the original "colors" namespace
    context = ray.init("ray://localhost:10001", namespace="colors")

    # This fails because "watermelon" was in the fruits namespace.
    try:
      ray.get_actor("watermelon")
    except ValueError:
      pass

    # This returns the "orange" actor we created in the first job, not the second.
    ray.get_actor("orange")

    # We are manually managing the scope of the connection in this example.
    context.disconnect()
finally:
    subprocess.check_output(["ray", "stop", "--force"])

Java

// `ray start --head` has been run to launch a local cluster.

// Job 1 creates two actors, "orange" and "purple" in the "colors" namespace.
System.setProperty("ray.address", "localhost:10001");
System.setProperty("ray.job.namespace", "colors");
try {
    Ray.init();
    Ray.actor(Actor::new).setName("orange").remote();
    Ray.actor(Actor::new).setName("purple").remote();
} finally {
    Ray.shutdown();
}

// Job 2 is now connecting to a different namespace.
System.setProperty("ray.address", "localhost:10001");
System.setProperty("ray.job.namespace", "fruits");
try {
    Ray.init();
    // This fails because "orange" was defined in the "colors" namespace.
    Ray.getActor("orange").isPresent(); // return false
    // This succceeds because the name "orange" is unused in this namespace.
    Ray.actor(Actor::new).setName("orange").remote();
    Ray.actor(Actor::new).setName("watermelon").remote();
} finally {
    Ray.shutdown();
}

// Job 3 connects to the original "colors" namespace.
System.setProperty("ray.address", "localhost:10001");
System.setProperty("ray.job.namespace", "colors");
try {
    Ray.init();
    // This fails because "watermelon" was in the fruits namespace.
    Ray.getActor("watermelon").isPresent(); // return false
    // This returns the "orange" actor we created in the first job, not the second.
    Ray.getActor("orange").isPresent(); // return true
} finally {
    Ray.shutdown();
}

C++

// `ray start --head` has been run to launch a local cluster.

// Job 1 creates two actors, "orange" and "purple" in the "colors" namespace.
ray::RayConfig config;
config.ray_namespace = "colors";
ray::Init(config);
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("orange").Remote();
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("purple").Remote();
ray::Shutdown();

// Job 2 is now connecting to a different namespace.
ray::RayConfig config;
config.ray_namespace = "fruits";
ray::Init(config);
// This fails because "orange" was defined in the "colors" namespace.
ray::GetActor<Counter>("orange"); // return nullptr;
// This succeeds because the name "orange" is unused in this namespace.
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("orange").Remote();
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("watermelon").Remote();
ray::Shutdown();

// Job 3 connects to the original "colors" namespace.
ray::RayConfig config;
config.ray_namespace = "colors";
ray::Init(config);
// This fails because "watermelon" was in the fruits namespace.
ray::GetActor<Counter>("watermelon"); // return nullptr;
// This returns the "orange" actor we created in the first job, not the second.
ray::GetActor<Counter>("orange");
ray::Shutdown();

Specifying namespace for named actors

You can specify a namespace for a named actor while creating it. The created actor belongs to the specified namespace, no matter what namespace of the current job is.

Python

import subprocess
import ray

try:
    subprocess.check_output(["ray", "start", "--head"])

    @ray.remote
    class Actor:
        pass

    ctx = ray.init("ray://localhost:10001")

    # Create an actor with specified namespace.
    Actor.options(name="my_actor", namespace="actor_namespace", lifetime="detached").remote()

    # It is accessible in its namespace.
    ray.get_actor("my_actor", namespace="actor_namespace")
    ctx.disconnect()
finally:
    subprocess.check_output(["ray", "stop", "--force"])

Java

// `ray start --head` has been run to launch a local cluster.

System.setProperty("ray.address", "localhost:10001");
try {
    Ray.init();
    // Create an actor with specified namespace.
    Ray.actor(Actor::new).setName("my_actor", "actor_namespace").remote();
    // It is accessible in its namespace.
    Ray.getActor("my_actor", "actor_namespace").isPresent(); // return true

} finally {
    Ray.shutdown();
}

C++

// `ray start --head` has been run to launch a local cluster.
ray::RayConfig config;
ray::Init(config);
// Create an actor with specified namespace.
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("my_actor", "actor_namespace").Remote();
// It is accessible in its namespace.
ray::GetActor<Counter>("orange");
ray::Shutdown();`

Anonymous namespaces

When a namespace is not specified, Ray will place your job in an anonymous namespace. In an anonymous namespace, your job will have its own namespace and will not have access to actors in other namespaces.

Python

import subprocess
import ray

try:
  subprocess.check_output(["ray", "start", "--head"])

  @ray.remote
  class Actor:
      pass

  # Job 1 connects to an anonymous namespace by default
  with ray.init("ray://localhost:10001"):
    Actor.options(name="my_actor", lifetime="detached").remote()

  # Job 2 connects to a _different_ anonymous namespace by default
  with ray.init("ray://localhost:10001"):
    # This succeeds because the second job is in its own namespace.
    Actor.options(name="my_actor", lifetime="detached").remote()

finally:
    subprocess.check_output(["ray", "stop", "--force"])

Java

// `ray start --head` has been run to launch a local cluster.

// Job 1 connects to an anonymous namespace by default.
System.setProperty("ray.address", "localhost:10001");
try {
    Ray.init();
    Ray.actor(Actor::new).setName("my_actor").remote();
} finally {
    Ray.shutdown();
}

// Job 2 connects to a _different_ anonymous namespace by default
System.setProperty("ray.address", "localhost:10001");
try {
    Ray.init();
    // This succeeds because the second job is in its own namespace.
    Ray.actor(Actor::new).setName("my_actor").remote();
} finally {
    Ray.shutdown();
}

C++

// `ray start --head` has been run to launch a local cluster.

// Job 1 connects to an anonymous namespace by default.
ray::RayConfig config;
ray::Init(config);
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("my_actor").Remote();
ray::Shutdown();

// Job 2 connects to a _different_ anonymous namespace by default
ray::RayConfig config;
ray::Init(config);
// This succeeds because the second job is in its own namespace.
ray::Actor(RAY_FUNC(Counter::FactoryCreate)).SetName("my_actor").Remote();
ray::Shutdown();

Note

Anonymous namespaces are implemented as UUID’s. This makes it possible for a future job to manually connect to an existing anonymous namespace, but it is not recommended.

Getting the current namespace

You can access to the current namespace using runtime_context APIs.

Python

import subprocess
import ray

try:
  subprocess.check_output(["ray", "start", "--head"])

  ray.init(address="auto", namespace="colors")

  # Will print namespace name "colors".
  print(ray.get_runtime_context().namespace)

finally:
    subprocess.check_output(["ray", "stop", "--force"])

Java

System.setProperty("ray.job.namespace", "colors");
try {
    Ray.init();
    // Will print namespace name "colors".
    System.out.println(Ray.getRuntimeContext().getNamespace());
} finally {
    Ray.shutdown();
}

C++

ray::RayConfig config;
config.ray_namespace = "colors";
ray::Init(config);
// Will print namespace name "colors".
std::cout << ray::GetNamespace() << std::endl;
ray::Shutdown();