[Doc] Revamp ray core design patterns doc [3/n]: ray get in a loop

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

@@ -0,0 +1,25 @@
+# __anti_pattern_start__
+import ray
+
+ray.init()
+
+
+@ray.remote
+def f(i):
+    return i
+
+
+# Anti-pattern: no parallelism due to calling ray.get inside of the loop.
+sequential_returns = []
+for i in range(100):
+    sequential_returns.append(ray.get(f.remote(i)))
+
+# Better approach: parallelism because the tasks are executed in parallel.
+refs = []
+for i in range(100):
+    refs.append(f.remote(i))
+
+parallel_returns = ray.get(refs)
+# __anti_pattern_end__
+
+assert sequential_returns == parallel_returns

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

@@ -9,4 +9,5 @@ This section is a collection of common design patterns and anti-patterns for wri
     :maxdepth: 1
 
     generators
+    ray-get-loop
     too-fine-grained-tasks

doc/source/ray-core/patterns/ray-get-loop.rst

@@ -0,0 +1,27 @@
+.. _ray-get-loop:
+
+Anti-pattern: Calling ray.get in a loop harms parallelism
+=========================================================
+
+**TLDR:** Avoid calling :ref:`ray.get() <ray-get-ref>` in a loop since it's blocking; call ``ray.get()`` only for the final result.
+
+A call to ``ray.get()`` fetches the results of remotely executed functions. However, it is a blocking call, which means that it always waits until the requested result is available.
+If you call ``ray.get()`` in a loop, the loop will not continue to run until the call to ``ray.get()`` was resolved.
+
+If you also spawn the remote function calls in the same loop, you end up with no parallelism at all, as you wait for the previous function call to finish (because of ``ray.get()``) and only spawn the next call in the next iteration of the loop.
+The solution here is to separate the call to ``ray.get()`` from the call to the remote functions. That way all remote processes are spawned before we wait for the results and can run in parallel in the background. Additionally, you can pass a list of object references to ``ray.get()`` instead of calling it one by one to wait for all of the tasks to finish.
+
+Code example
+------------
+
+.. literalinclude:: ../doc_code/anti_pattern_ray_get_loop.py
+    :language: python
+    :start-after: __anti_pattern_start__
+    :end-before: __anti_pattern_end__
+
+.. figure:: ../images/ray-get-loop.svg
+
+    Calling ``ray.get()`` in a loop
+
+When calling ``ray.get()`` right after scheduling the remote work, the loop blocks until the result is received. We thus end up with sequential processing.
+Instead, we should first schedule all remote calls, which are then processed in parallel. After scheduling the work, we can then request all the results at once.

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

@@ -18,7 +18,6 @@ You may also be interested in visiting the design patterns section for :ref:`act
     limit-tasks
     closure-capture
     global-variables
-    ray-get-loop
     submission-order
     too-many-results
     redefine-task-actor-loop