Skip to content

moveit_py: release the GIL in plan(), the collision checks and set_from_ik (backport #3935) - #3979

Open
mergify[bot] wants to merge 1 commit into
jazzyfrom
mergify/bp/jazzy/pr-3935
Open

mergify[bot] wants to merge 1 commit into
jazzyfrom
mergify/bp/jazzy/pr-3935

Conversation

@mergify

@mergify mergify Bot commented Nov 17, 2026

Copy link
Copy Markdown

Target: main (label backport-jazzy for the Jazzy release the cells run, 2.12.x).

Description

PlanningComponent.plan() holds the Python GIL for the whole plan, which can take seconds. Every
other Python thread of the process is frozen for that long: ROS callbacks and timers of the node,
tf listeners, an HTTP server. MoveItPy.execute() already releases the GIL for the same reason
(#2573). This does the same for:

  1. PlanningComponent.plan() (py::call_guard<py::gil_scoped_release>). The two optional Python
    callbacks (solution_selection_function, stopping_criterion_callback) keep working: pybind11's
    std::function caster takes the GIL back around each call into Python.
  2. The collision queries of PlanningScene (is_state_valid, is_state_colliding,
    check_collision, check_self_collision, is_path_valid) and RobotState.set_from_ik. These
    are the calls a reachability or validity check makes in bulk; released, they can run on worker
    threads while the node keeps spinning.

Measured on a Techman TM arm with a Python node that plans while it serves /status over HTTP and
listens to tf (MoveIt 2.12.4, Jazzy): with the GIL held, /status took up to 2.7 s during moves and
5-7 of 20 moves failed with a tf ExtrapolationException (the Python tf listener lagged 0.76 s
behind) whenever a planning request ran alongside; released, /status stayed under 0.4 s and 0 of
20 moves failed, over two runs each.

Note for reviewers: with the GIL released, two Python threads can enter the same
PlanningComponent, PlanningScene or RobotState at once (for instance, one reads
joint_positions while another runs set_from_ik on the same state), which the GIL used to prevent
as a side effect. Those objects are not thread-safe in C++ either; callers who share one across
threads must serialize their calls themselves (we do so with a per-instance lock). This matches how
execute() behaves today.

Checklist

  • Code is auto formatted using clang-format (14.0.6, the pre-commit pin)
  • Extend the tutorials / documentation reference: n/a (no API change)
  • Document API changes relevant to the user in the MIGRATION.md notes: n/a (no API change)
  • Create tests, which fail without this PR: none added. moveit_py/test/unit has no planner or
    kinematics solver loaded (test_set_from_ik is commented out for that reason) and the
    integration test directory is empty, so a test that measures another thread's progress during
    a long plan() or set_from_ik(timeout=...) call has nowhere to run yet. Happy to add one if
    a fixture with a kinematics plugin is acceptable.
  • Include a screenshot if changing a GUI: n/a
  • While waiting for someone to review your request, please help review another open pull request

Summary by CodeRabbit

  • Performance
    • Planning, inverse-kinematics, collision checking, and validity checks now allow other Python threads to run while these operations execute.
  • Important
    • Avoid accessing the planning component, planning scene, or relevant robot state from another Python thread while an operation is running. Calls using a scene’s current state may also update collision transforms, so concurrent calls on the same scene are unsafe, even when using a read-only monitor.

This is an automatic backport of pull request #3935 done by [Mergify](https://mergify.com).

…om_ik (#3935)

* moveit_py: PlanningComponent.plan() releases the GIL

* moveit_py: collision checks and set_from_ik release the GIL

* moveit_py: check_self_collision releases the GIL

The other collision queries of PlanningScene already do; the three
check_self_collision overloads were missed.

* moveit_py: note in the docstrings which GIL-releasing calls write state

Apply the review suggestions: the calls that write to the object or to the
passed state while the GIL is released now say so, and that the object must
not be used from another Python thread meanwhile.

Co-authored-by: Nathan Brooks <nathanbrooks@picknik.ai>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* moveit_py: plan() note as a Note section, warn that read_only() is a shared lock

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* moveit_py: test that the collision checks release the GIL

A second Python thread counts while the main thread runs a collision check in
a loop. The switch interval is raised to 30 s, so the counter only advances
while the binding releases the GIL: about 3000 ticks in 0.5 s with the guard,
1 without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Matthijs van der Burgh <matthijs.van.der.burgh@vbti.nl>
Co-authored-by: Nathan Brooks <nathanbrooks@picknik.ai>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit b9bf61e)
@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: fdfaeb5c-9cd1-4cbb-abde-a5bc9366f295

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@mergify

mergify Bot commented Nov 17, 2026

Copy link
Copy Markdown
Author

Tick the box to add this pull request to the merge queue (same as @mergifyio queue). If it does not match the queue conditions yet, it enters the queue once it does.

  • Queue this pull request

@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 46.30%. Comparing base (f11204b) to head (e95ae88).

Files with missing lines Patch % Lines
...oveit/moveit_ros/moveit_cpp/planning_component.cpp 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##            jazzy    #3979      +/-   ##
==========================================
+ Coverage   46.27%   46.30%   +0.03%     
==========================================
  Files         718      718              
  Lines       59236    59254      +18     
  Branches     7598     7612      +14     
==========================================
+ Hits        27405    27430      +25     
+ Misses      31666    31659       -7     
  Partials      165      165              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant