[Data] Fix reference cycle in by moving to module scope by Crystora · Pull Request #61934 · ray-project/ray

Crystora · 2026-03-21T08:58:24Z

Description

Fix reference cycle in ActorMethod.options() by moving FuncWrapper to module scope.

The old FuncWrapper class was defined inside the options() closure, which triggered CPython's implicit __class__ cell. This kept the ActorMethod and its ActorHandle alive until the cyclic GC ran, delaying __ray_shutdown__ and actor cleanup.

The fix replaces it with _ActorMethodOptionsWrapper at module scope. Same interface, no closure, no cycle.

Related issues

Fixes #61922

Additional information

Added regression test test_options_no_ref_cycle that disables GC and asserts the ActorHandle is freed by reference counting alone after options().remote().

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

gemini-code-assist

Code Review

This pull request fixes a reference cycle in ActorMethod.options() by moving an inner class to module scope. This prevents a closure from keeping actor-related objects alive, ensuring proper garbage collection. The change is accompanied by a new regression test that validates the fix by disabling the garbage collector and checking for leaks using weak references. The implementation appears correct and complete.

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

…r-method-options-ref-cycle

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

Crystora · 2026-03-23T16:10:36Z

@edoakes All tests passed. what else should I need to update?

edoakes · 2026-03-23T22:04:46Z

@codope could you please help review? I remember you working on something similar as one of your first tickets

Crystora · 2026-03-24T03:06:05Z

@codope would you please review this pr? welcome to any feedbacks.
thank you

codope

@bittoby thanks for the fix! Overall, looks good to me. Left a couple of comments. PTAL.

codope · 2026-03-24T04:01:42Z

-        class FuncWrapper:
-            def remote(self, *args, **kwargs):
-                return func_cls._remote(args=args, kwargs=kwargs, **options)
-
-            @DeveloperAPI
-            def bind(self, *args, **kwargs):
-                return func_cls._bind(args=args, kwargs=kwargs, **options)
-
-        return FuncWrapper()
+        return _ActorMethodOptionsWrapper(self, options)


There's an identical FuncWrapper-inside-closure pattern in remote_function.py:

ray/python/ray/remote_function.py

Line 291 in fe32fba

class FuncWrapper:

It has the same __class__ cell cycle. The impact is lower (no ActorHandle or __ray_shutdown__ involved), but can you check if it still creates an unnecessary garbage island on every .options() call? Maybe worth a follow-up fix for consistency.

Yes, remote_function.py has the same __class__ cell cycle. It creates a small garbage island on every .options() call, though the impact is lower since RemoteFunction objects are long-lived and no ActorHandle/__ray_shutdown__ is involved. I'll send a follow-up PR to fix it for consistency.

sounds good, please tag me on the follow-up PR when it's ready.

…r-method-options-ref-cycle

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

Crystora · 2026-03-24T04:34:42Z

@codope Thanks for your feedback! I updated all following your feedback. Could you review again?

Crystora · 2026-03-24T10:49:24Z

@edoakes would you merge this PR? This testing failure is not relate to my change. Thanks

edoakes · 2026-03-24T14:25:56Z

Thanks @bittoby!

## Description In #61700, a direct call to `_remote()` is used as workaround to get over the issue described in #61922. This issue has been fixed in #61934 and this PR changes the direct `_remote()` call back to the method chaining style. ## Related issues Related to #61922. --------- Signed-off-by: Sirui Huang <ray.huang@anyscale.com> Signed-off-by: HFFuture <ray.huang@anyscale.com> Co-authored-by: Hao Chen <chenh1024@gmail.com>

…61934) ## Description Fix reference cycle in `ActorMethod.options()` by moving `FuncWrapper` to module scope. The old `FuncWrapper` class was defined inside the `options()` closure, which triggered CPython's implicit `__class__` cell. This kept the `ActorMethod` and its `ActorHandle` alive until the cyclic GC ran, delaying `__ray_shutdown__` and actor cleanup. The fix replaces it with `_ActorMethodOptionsWrapper` at module scope. Same interface, no closure, no cycle. ## Related issues Fixes ray-project#61922 ## Additional information Added regression test `test_options_no_ref_cycle` that disables GC and asserts the `ActorHandle` is freed by reference counting alone after `options().remote()`. --------- Signed-off-by: bittoby <bittoby@users.noreply.github.com> Co-authored-by: bittoby <bittoby@users.noreply.github.com>

## Description In ray-project#61700, a direct call to `_remote()` is used as workaround to get over the issue described in ray-project#61922. This issue has been fixed in ray-project#61934 and this PR changes the direct `_remote()` call back to the method chaining style. ## Related issues Related to ray-project#61922. --------- Signed-off-by: Sirui Huang <ray.huang@anyscale.com> Signed-off-by: HFFuture <ray.huang@anyscale.com> Co-authored-by: Hao Chen <chenh1024@gmail.com>

…61934) ## Description Fix reference cycle in `ActorMethod.options()` by moving `FuncWrapper` to module scope. The old `FuncWrapper` class was defined inside the `options()` closure, which triggered CPython's implicit `__class__` cell. This kept the `ActorMethod` and its `ActorHandle` alive until the cyclic GC ran, delaying `__ray_shutdown__` and actor cleanup. The fix replaces it with `_ActorMethodOptionsWrapper` at module scope. Same interface, no closure, no cycle. ## Related issues Fixes ray-project#61922 ## Additional information Added regression test `test_options_no_ref_cycle` that disables GC and asserts the `ActorHandle` is freed by reference counting alone after `options().remote()`. --------- Signed-off-by: bittoby <bittoby@users.noreply.github.com> Co-authored-by: bittoby <bittoby@users.noreply.github.com>

## Description In ray-project#61700, a direct call to `_remote()` is used as workaround to get over the issue described in ray-project#61922. This issue has been fixed in ray-project#61934 and this PR changes the direct `_remote()` call back to the method chaining style. ## Related issues Related to ray-project#61922. --------- Signed-off-by: Sirui Huang <ray.huang@anyscale.com> Signed-off-by: HFFuture <ray.huang@anyscale.com> Co-authored-by: Hao Chen <chenh1024@gmail.com>

fix: Fix reference cycle in by moving to module scope

d2db47e

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

Crystora requested a review from a team as a code owner March 21, 2026 08:58

gemini-code-assist Bot reviewed Mar 21, 2026

View reviewed changes

ray-gardener Bot added core Issues that should be addressed in Ray Core data Ray Data-related issues community-contribution Contributed by the community labels Mar 21, 2026

edoakes added the go add ONLY when ready to merge, run all tests label Mar 23, 2026

update

d7153f8

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

Crystora force-pushed the fix-actor-method-options-ref-cycle branch from 4e06aeb to d7153f8 Compare March 23, 2026 04:50

bittoby added 2 commits March 23, 2026 04:51

Merge branch 'master' of https://github.com/bittoby/ray into fix-acto…

e8d3792

…r-method-options-ref-cycle

fix: solve testing error

9cdf054

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

edoakes assigned codope Mar 23, 2026

codope reviewed Mar 24, 2026

View reviewed changes

bittoby added 2 commits March 24, 2026 04:30

Merge branch 'master' of https://github.com/bittoby/ray into fix-acto…

6b2dc74

…r-method-options-ref-cycle

fix: Move after and fix test fixture

e731906

Signed-off-by: bittoby <bittoby@users.noreply.github.com>

codope approved these changes Mar 24, 2026

View reviewed changes

edoakes merged commit 7985f5d into ray-project:master Mar 24, 2026
5 of 6 checks passed

Crystora deleted the fix-actor-method-options-ref-cycle branch March 24, 2026 14:28

rayhhome mentioned this pull request Mar 24, 2026

[Data] Revert ActorMethod Reference Cycle Workaround #62036

Merged

edoakes mentioned this pull request Mar 25, 2026

fix(core): break ActorMethod.options() reference cycle (#61922) #62044

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Data] Fix reference cycle in by moving to module scope#61934

[Data] Fix reference cycle in by moving to module scope#61934
edoakes merged 6 commits into
ray-project:masterfrom
Crystora:fix-actor-method-options-ref-cycle

Crystora commented Mar 21, 2026

gemini-code-assist Bot left a comment

Crystora commented Mar 23, 2026 •

edited

Loading

edoakes commented Mar 23, 2026

Crystora commented Mar 24, 2026

codope left a comment

Uh oh!

codope Mar 24, 2026

Crystora Mar 24, 2026

codope Mar 24, 2026

Crystora commented Mar 24, 2026

Crystora commented Mar 24, 2026

Uh oh!

edoakes commented Mar 24, 2026

Labels

3 participants

Uh oh!

Conversation

Crystora commented Mar 21, 2026

Description

Related issues

Additional information

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Crystora commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

edoakes commented Mar 23, 2026

Crystora commented Mar 24, 2026

codope left a comment

Choose a reason for hiding this comment

Uh oh!

codope Mar 24, 2026

Choose a reason for hiding this comment

Crystora Mar 24, 2026

Choose a reason for hiding this comment

codope Mar 24, 2026

Choose a reason for hiding this comment

Crystora commented Mar 24, 2026

Crystora commented Mar 24, 2026

Uh oh!

edoakes commented Mar 24, 2026

Labels

3 participants

Crystora commented Mar 23, 2026 •

edited

Loading