[Doc] Revamp ray core design patterns doc [12/n]: global variables (r…

…ay-project#29124)

Signed-off-by: Jiajun Yao <[email protected]>
Signed-off-by: Stephanie Wang <[email protected]>
Co-authored-by: Stephanie Wang <[email protected]>

doc/source/ray-core/doc_code/anti_pattern_global_variables.py

@@ -0,0 +1,51 @@
+# __anti_pattern_start__
+import ray
+
+ray.init()
+
+global_var = 3
+
+
+@ray.remote
+class Actor:
+ def f(self):
+ return global_var + 3
+
+
+actor = Actor.remote()
+global_var = 4
+# This returns 6, not 7. It is because the value change of global_var
+# inside a driver is not reflected to the actor
+# because they are running in different processes.
+assert ray.get(actor.f.remote()) == 6
+# __anti_pattern_end__
+
+
+# __better_approach_start__
+@ray.remote
+class GlobalVarActor:
+ def __init__(self):
+ self.global_var = 3
+
+ def set_global_var(self, var):
+ self.global_var = var
+
+ def get_global_var(self):
+ return self.global_var
+
+
+@ray.remote
+class Actor:
+ def __init__(self, global_var_actor):
+ self.global_var_actor = global_var_actor
+
+ def f(self):
+ return ray.get(self.global_var_actor.get_global_var.remote()) + 3
+
+
+global_var_actor = GlobalVarActor.remote()
+actor = Actor.remote(global_var_actor)
+ray.get(global_var_actor.set_global_var.remote(4))
+# This returns 7 correctly.
+assert ray.get(actor.f.remote()) == 7
+# __better_approach_end__

doc/source/ray-core/patterns/global-variables.rst

@@ -0,0 +1,30 @@
+Anti-pattern: Using global variables to share state between tasks and actors
+============================================================================
+
+**TLDR:** Don't use global variables to share state with tasks and actors. Instead, encapsulate the global variables in an actor and pass the actor handle to other tasks and actors.
+
+Ray drivers, tasks and actors are running in
+different processes, so they don’t share the same address space.
+This means that if you modify global variables
+in one process, changes are not reflected in other processes.
+
+The solution is to use an actor's instance variables to hold the global state and pass the actor handle to places where the state needs to be modified or accessed.
+Note that using class variables to manage state between instances of the same class is not supported.
+Each actor instance is instantiated in its own process, so each actor will have its own copy of the class variables.
+
+Code example
+------------
+
+**Anti-pattern:**
+
+.. literalinclude:: ../doc_code/anti_pattern_global_variables.py
+ :language: python
+ :start-after: __anti_pattern_start__
+ :end-before: __anti_pattern_end__
+
+**Better approach:**
+
+.. literalinclude:: ../doc_code/anti_pattern_global_variables.py
+ :language: python
+ :start-after: __better_approach_start__
+ :end-before: __better_approach_end__

doc/source/ray-core/patterns/index.rst

@@ -19,3 +19,4 @@ This section is a collection of common design patterns and anti-patterns for wri
  redefine-task-actor-loop
  pass-large-arg-by-value
  closure-capture-large-objects
+ global-variables

doc/source/ray-core/tasks/patterns/index.rst

@@ -15,4 +15,3 @@ You may also be interested in visiting the design patterns section for :ref:`act
 
  tree-of-tasks
  map-reduce
- global-variables