Revamp ray core design patterns doc [10/n]: closure capture large obj…

…ects (ray-project#28953)

Signed-off-by: Jiajun Yao <[email protected]>

    Edit pass: fix some wordings and format
    Move code to doc_code folder

Related issue number

ray-project#27048

Signed-off-by: Weichen Xu <[email protected]>

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

@@ -0,0 +1,44 @@
+# __anti_pattern_start__
+import ray
+import numpy as np
+
+ray.init()
+
+large_object = np.zeros(10 * 1024 * 1024)
+
+
+@ray.remote
+def f1():
+    return len(large_object)  # large_object is serialized along with f1!
+
+
+ray.get(f1.remote())
+# __anti_pattern_end__
+
+# __better_approach_1_start__
+large_object_ref = ray.put(np.zeros(10 * 1024 * 1024))
+
+
+@ray.remote
+def f2(large_object):
+    return len(large_object)
+
+
+# Large object is passed through object store.
+ray.get(f2.remote(large_object_ref))
+# __better_approach_1_end__
+
+# __better_approach_2_start__
+large_object_creator = lambda: np.zeros(10 * 1024 * 1024)  # noqa E731
+
+
+@ray.remote
+def f3():
+    large_object = (
+        large_object_creator()
+    )  # Lambda is small compared with the large object.
+    return len(large_object)
+
+
+ray.get(f3.remote())
+# __better_approach_2_end__

doc/source/ray-core/patterns/closure-capture-large-objects.rst

@@ -0,0 +1,38 @@
+Anti-pattern: Closure capturing large objects harms performance
+===============================================================
+
+**TLDR:** Avoid closure capturing large objects in remote functions or classes, use object store instead.
+
+When you define a :ref:`ray.remote() <ray-remote-ref>` function or class,
+it is easy to accidentally capture large (more than a few MB) objects implicitly in the definition.
+This can lead to slow performance or even OOM since Ray is not designed to handle serialized functions or classes that are very large.
+
+For such large objects, there are two options to resolve this problem:
+
+- Use :ref:`ray.put() <ray-put-ref>` to put the large objects in the Ray object store, and then pass object references as arguments to the remote functions or classes (*"better approach #1"* below)
+- Create the large objects inside the remote functions or classes by passing a lambda method (*"better approach #2"*). This is also the only option for using unserializable objects.
+
+
+Code example
+------------
+
+**Anti-pattern:**
+
+.. literalinclude:: ../doc_code/anti_pattern_closure_capture_large_objects.py
+    :language: python
+    :start-after: __anti_pattern_start__
+    :end-before: __anti_pattern_end__
+
+**Better approach #1:**
+
+.. literalinclude:: ../doc_code/anti_pattern_closure_capture_large_objects.py
+    :language: python
+    :start-after: __better_approach_1_start__
+    :end-before: __better_approach_1_end__
+
+**Better approach #2:**
+
+.. literalinclude:: ../doc_code/anti_pattern_closure_capture_large_objects.py
+    :language: python
+    :start-after: __better_approach_2_start__
+    :end-before: __better_approach_2_end__

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

@@ -17,3 +17,4 @@ This section is a collection of common design patterns and anti-patterns for wri
     too-fine-grained-tasks
     redefine-task-actor-loop
     pass-large-arg-by-value
+    closure-capture-large-objects

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

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