[core][doc] ray.get with timeout=0 will warn behavior change in futur…

…e ray releases. (#31140)

With ray. get(timeout=0) currently blocks until objects are ready, which is not the ideal behavior. Since there might be existing users depending on such behavior. We will fix this with a more gradual migration in future releases as we gather current usage.

Besides this PR, we will:

Reach out on the slack channel about this behavior change
Add telemetry for usage.
Fix this in future ray release

python/ray/_private/worker.py

@@ -2281,7 +2281,13 @@ def get(
         object_refs: Object ref of the object to get or a list of object refs
             to get.
         timeout (Optional[float]): The maximum amount of time in seconds to
-            wait before returning.
+            wait before returning. Set this to None will block until the
+            corresponding object becomes available.
+            WARNING: In future ray releases ``timeout=0`` will return the object
+            immediately if it's available, else raise GetTimeoutError in accordance with
+            the above docstring. The current behavior of blocking until objects become
+            available of ``timeout=0`` is considered to be a bug, see
+            https://github.com/ray-project/ray/issues/28465.
 
     Returns:
         A Python object or a list of Python objects.
@@ -2292,6 +2298,21 @@ def get(
         Exception: An exception is raised if the task that created the object
             or that created one of the objects raised an exception.
     """
+    if timeout == 0:
+        if os.environ.get("RAY_WARN_RAY_GET_TIMEOUT_ZERO", "1") == "1":
+            import warnings
+
+            warnings.warn(
+                (
+                    "Please use timeout=None if you expect ray.get() to block. "
+                    "Setting timeout=0 in future ray releases will raise "
+                    "GetTimeoutError if the objects references are not available. "
+                    "You could suppress this warning by setting "
+                    "RAY_WARN_RAY_GET_TIMEOUT_ZERO=0."
+                ),
+                UserWarning,
+            )
+
     worker = global_worker
     worker.check_connected()
 

python/ray/tests/test_advanced_2.py

@@ -520,6 +520,21 @@ def test():
     assert cluster_resources == {}
 
 
+def test_ray_get_timeout_zero(monkeypatch):
+    # Check that ray.get(timeout=0) raises warnings on change of behavior.
+    # Removed when https://github.com/ray-project/ray/issues/28465 is resolved.
+    with pytest.warns(UserWarning):
+        ray.get(ray.put(1), timeout=0)
+
+    with monkeypatch.context() as m:
+        m.setenv("RAY_WARN_RAY_GET_TIMEOUT_ZERO", "0")
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            ray.get(ray.put(1), timeout=0)
+
+
 if __name__ == "__main__":
     if os.environ.get("PARALLEL_CI"):
         sys.exit(pytest.main(["-n", "auto", "--boxed", "-vs", __file__]))