[Doc][namespaces][C++ worker]add document for c++ worker namespace an…

…d specifying namespace while creating/getting named actors (ray-project#26498)

We've supported namespace in c++ worker in ray-project#26327. Here we add doc for usage and also reinforce the documents of Java and Python, like adding explanation of specifying namespace while creating named actors.

- [x] add doc for basic c++ worker namespace usage
- [x] add explanation for specifying namespace while creating named actors, in Python, Java and C++

Signed-off-by: Stefan van der Kleij <[email protected]>

doc/source/ray-core/namespaces.rst

@@ -24,6 +24,14 @@ first connect to the cluster.
  System.setProperty("ray.job.namespace", "hello"); // set it before Ray.init()
  Ray.init();
 
+.. tabbed:: C++
+
+ .. code-block:: c++
+
+ ray::RayConfig config;
+ config.ray_namespace = "hello";
+ ray::Init(config);
+
 Please refer to `Driver Options <configure.html#driver-options>`__ for ways of configuring a Java application.
 
 Named actors are only accessible within their namespaces.
@@ -105,6 +113,98 @@ Named actors are only accessible within their namespaces.
  Ray.shutdown();
  }
 
+.. tabbed:: C++
+
+ .. code-block:: 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 succceeds 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.
+
+.. tabbed:: Python
+
+ .. code-block:: python
+
+ # `ray start --head` has been run to launch a local cluster
+
+ import ray
+
+ @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()
+
+.. tabbed:: Java
+
+ .. code-block:: 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();
+ }
+
+.. tabbed:: C++
+
+ .. code-block:: 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
 --------------------
 
@@ -160,6 +260,25 @@ will not have access to actors in other namespaces.
  Ray.shutdown();
  }
 
+.. tabbed:: C++
+
+ .. code-block:: 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