Skip to content

Threading and the GIL

Every binding that releases the GIL is listed with its reason in scripts/nogil_entry_points.yaml (#124). Every other binding holds the GIL for the whole call. The list is checked, not trusted: pixi run -e audit audit-gil parses every binding TU and fails CI when a binding and the list disagree, in either direction. Run-time tests check that each release added by #124 really drops the GIL. New candidates come from measurement: pixi run gil-hotspots ranks the bindings that hold the GIL longest in the benchmarks and the test suite.

Every Environment method releases the GIL, init and getKinematicGroup included: a thread never waits for an environment's lock while it holds the GIL, which is what made a Python event callback deadlock against a writer on another thread (see Environment event callbacks). The plugin factories stay GIL-held until upstream synchronises their caches (see Upstream).

Confirmed

audit-gil: 64 releases, all listed (macOS arm64, 2026-11-08). The audit's contract tests (pixi run -e audit audit-test), the run-time release tests and the full test suite passed at 47 releases (macOS arm64, Python 3.14, 2026-10-24).

Incomplete

The plugin-factory releases are remaining work, and scripts/nogil_entry_points.yaml must list the Environment releases before the next audit-gil run: see Remaining work.

The rule

Release the GIL around a call only when all three hold:

  1. It is expensive or blocking. Roughly above 50 µs, or it can wait: planning, IK, collision checks over a trajectory, time parameterization, URDF and mesh loading, waiting on a task composer future. A call that blocks on a C++ lock which a thread waiting for the GIL may hold counts too (Environment.getState, clone, ==).
  2. It runs pure C++. No Python object is created, copied or dropped in the released region. Python callbacks stay safe: nanobind trampolines (NB_OVERRIDE) and the std::function caster re-acquire the GIL themselves, as do the bindings' own callback wrappers and nanobind's shared_ptr deleter for a Python-owned object.
  3. It does not mutate state Python code typically shares across threads. Releasing the GIL lets other Python threads run. A C++ object that is not thread-safe was protected by the GIL while the call held it; after the release, two threads can race on it.

Value types, getters, setters and constructors never qualify.

Whatever the released region reads must stay alive without the GIL. A C++ closure holding a raw reference to a Python-owned object breaks this: another thread can drop the object during the call. The closure has to hold a shared_ptr to it, as makeImplicitSDFShape's callables do.

A released call that reads a Python-assignable member in place races a thread assigning it. collideImplicitSDF avoids this by copying its shapes and config with the GIL held, before the release. Other releases leave it to the caller: assigning ContactRequest.is_valid during contactTest is the caller's race. The other entries have not been checked one by one, so don't assign to an argument of a released call while it runs.

How to release it

nanobind has no global switch like SWIG's -threads. Per binding there are two forms:

C++
// The whole native call: arguments are converted before the release,
// the result is converted after the GIL is re-acquired.
.def("solve", &tp::MotionPlanner::solve, "request"_a, nb::call_guard<nb::gil_scoped_release>())

// Part of a lambda: validate (and raise Python errors) with the GIL held, then release.
.def("checkTrajectoryState", [](Manager& manager, const tc::TransformMap& state, ...) {
    require_active_link_transforms(manager, state, "checkTrajectoryState", "state");
    nb::gil_scoped_release release;
    ...
})

Use the in-body form when the lambda has to raise or touch Python objects before or after the native call. Under call_guard, by-value arguments are destroyed without the GIL, so a binding that takes nb::object, nb::handle, nb::callable, nb::bytes or nb::args must not use it.

How the list is enforced

flowchart LR
    subgraph static["Static: audit.yml, on merge to main, on tags, by hand"]
        tu["binding TUs<br/>src/bindings/*.cpp"] --> audit["audit_gil.py<br/>(libclang, bodies parsed)"]
        yaml["nogil_entry_points.yaml"] --> audit
        audit -->|"release not listed,<br/>or listed but gone"| fail["CI fails"]
    end
    subgraph runtime["Run time"]
        oracle["test_gil_entry_points.py<br/>switch-interval oracle"]
        hot["gil-hotspots<br/>py-spy --gil + call counts"] --> cand["ranked candidates"]
        cand -->|"judged against the rule"| yaml
    end
    yaml -.->|"each #124 release"| oracle
    classDef staticNode fill:#e8eef7,stroke:#3b5b8c
    classDef runtimeNode fill:#f7efe3,stroke:#8c6a3b
    class tu,audit,yaml,fail staticNode
    class oracle,hot,cand runtimeNode

Adding or removing a release means editing the list in the same change. An entry names the Python module, the Python class (module for module-level functions) and the Python name, and covers every overload of that name that releases the GIL.

scripts/audit_gil.py finds a release in these forms:

Form Example in the bindings
nb::call_guard<nb::gil_scoped_release>() on a .def / m.def MotionPlanner.solve
nb::gil_scoped_release in the bound lambda checkTrajectoryState
a release in a main-file function, function template or local lambda the binding calls or binds checkTrajectory, KinematicGroup.calcInvKin (list overload)
a helper call given the guard; counts under the helper's name bind_value_equality(cls, guard)
a helper template that binds a releasing .def under the name its caller passes; counts under each name passed def_create_mesh_from_path<T>(m, "createMeshFromPath", ...)

It fails loudly rather than guess. A libclang error diagnostic fails the run (ParseError), because a partial AST would miss releases. A releasing .def whose Python class can't be named, such as a literal name on a template-parameter receiver, also fails the run (UnresolvedScopeError). It maps C++ classes to Python names through the nb::class_<T>(scope, "Name") constructors in the same TU.

YAML
# Every binding that releases the GIL, and why (#124). scripts/audit_gil.py fails CI when
# this list and the bindings disagree, in either direction; docs/developer/threading.md
# embeds this file.
#
# module (every TU of its binding: the primary and its parts, audit_ownership.MODULE_PARTS)
#   -> Python class (`module` for module-level functions) -> method: reason
# An entry covers every overload of that name that releases the GIL.
#
# The rule (docs/developer/threading.md): release the GIL only around a call that
#   1. is expensive or blocking (roughly > 50 us, or it can wait), or blocks on a C++ lock that a
#      thread waiting for the GIL can hold;
#   2. runs pure C++: no Python object is created, copied or dropped in the released region
#      (trampolines and the std::function caster re-acquire the GIL themselves);
#   3. does not mutate state Python code typically shares across threads.
# Value types, getters, setters and constructors never qualify.

task_composer:
  TaskComposerFuture:
    wait: >-
      Blocks until the executor finishes. Mandatory, not a speed-up: a Python profile or cost
      running on a worker thread needs the GIL, so holding it here deadlocks.
    waitFor: Blocks for up to `duration`; see wait.
    ready: >-
      Frees the finished runs once this one is done (as wait and waitFor do): dropping the last
      reference to an executor a server replaced joins its workers, which may wait for the GIL in
      a Python log handler. The runs' Python references are dropped before the release.
  TaskComposerNode:
    run: >-
      Runs the node in the calling thread; a graph or pipeline waits for its children on the
      executor's workers, which re-enter Python for Python profiles and log handlers.
  TaskComposerServer:
    loadConfig: >-
      Waits for another thread's loadConfig / addTask / addExecutor on this server (the server
      gate, enter_server), which calls Python (a ResourceLocator) and needs the GIL; a Python
      log handler waits there too, on the delivery thread; frees finished runs first (see
      TaskComposerFuture.ready). The load itself holds the GIL.
    addTask: Waits for another thread's mutation of this server; see loadConfig.
    addExecutor: >-
      Replacing an executor destroys the old one, which joins workers that may wait for the GIL
      in a Python callback; also waits for another thread's mutation (see loadConfig). Other
      server calls wait on the gate while it runs, so no Python thread sees it half done.
    run: >-
      Waits for another thread's mutation of this server, then schedules the task on the worker
      threads (see TaskComposerExecutor.run); frees finished runs first.
    getTask: >-
      Waits for another thread's mutation of this server (see loadConfig); releases nothing when
      none runs.
    hasTask: See getTask.
    getAvailableTasks: See getTask.
    getExecutor: See getTask.
    hasExecutor: See getTask.
    getAvailableExecutors: See getTask.
    getWorkerCount: See getTask.
    getTaskCount: See getTask.
  TaskComposerExecutor:
    run: >-
      Schedules the graph on the worker threads, which re-enter Python for Python profiles;
      the context and node are converted before the release.
  TaskflowTaskComposerExecutor:
    run: Re-exposed TaskComposerExecutor.run; same reason.

motion_planners:
  MotionPlanner:
    solve: Seconds of CPU for OMPL, TrajOpt, TrajOpt-Ifopt and Descartes.
  module:
    contactCheckProgram: Collision-checks every state of a program; pure C++ loop.
    assignCurrentStateAsSeed: >-
      Reads the environment under its lock (see environment.Environment.init).
    formatProgram: See assignCurrentStateAsSeed.
    toToolpath: See assignCurrentStateAsSeed; forward kinematics per waypoint.

motion_planners_simple:
  SimpleMotionPlanner:
    solve: >-
      Interpolates and runs IK for every segment; a Python move profile re-acquires the GIL
      through its trampoline.
  SimplePlannerMoveProfile:
    generate: Interpolation plus IK for one segment, called by the planner in a loop.
  module:
    generateInterpolatedProgram: >-
      Interpolates every segment and solves a state per step: ~0.1 s per call in the tests
      (gil-hotspots). Only reads env.
  # Bound by the template bind_instruction_info, named at its call sites.
  JointGroupInstructionInfo:
    __init__: Reads the environment under its lock (getJointGroup / getKinematicGroup).
  KinematicGroupInstructionInfo:
    __init__: See JointGroupInstructionInfo.__init__.

motion_planners_descartes:
  # Bound once for both scalar types by the template bind_descartes, named at its call sites.
  DescartesMoveProfileD:
    createKinematicGroup: >-
      Reads the environment under its lock (see motion_planners.assignCurrentStateAsSeed) and
      loads the IK plugin.
    createWaypointSampler: >-
      Reads the environment under its lock; a Python override takes the GIL in its trampoline.
    createEdgeEvaluator: See createWaypointSampler.
    createStateEvaluator: See createWaypointSampler.
  DescartesMoveProfileF:
    createKinematicGroup: See DescartesMoveProfileD.createKinematicGroup.
    createWaypointSampler: See DescartesMoveProfileD.createWaypointSampler.
    createEdgeEvaluator: See DescartesMoveProfileD.createEdgeEvaluator.
    createStateEvaluator: See DescartesMoveProfileD.createStateEvaluator.

motion_planners_trajopt_ifopt:
  TrajOptIfoptMoveProfile:
    create: Reads the environment under its lock; checks run with the GIL first.
  TrajOptIfoptCompositeProfile:
    create: See TrajOptIfoptMoveProfile.create.
  module:
    createCollisionConstraints: See TrajOptIfoptMoveProfile.create.

trajopt_ifopt:
  # Bound in the part trajopt_ifopt_collision.cpp.
  SingleTimestepCollisionEvaluator:
    __init__: Reads the environment under its lock (its contact manager).
  LVSDiscreteCollisionEvaluator:
    __init__: See SingleTimestepCollisionEvaluator.__init__.
  LVSContinuousCollisionEvaluator:
    __init__: See SingleTimestepCollisionEvaluator.__init__.

trajopt_sqp:
  TrustRegionSQPSolver:
    solve: Runs the full SQP optimization.

kinematics:
  InverseKinematics:
    calcInvKin: Numerical solvers (TRAC-IK, KDL) iterate until their timeout.
  KinematicGroup:
    calcInvKin: See InverseKinematics.calcInvKin; plus redundant-solution expansion.
  module:
    checkKinematics: FK then IK for every working frame and tip link.
    calcManipulabilityVolume_each: One JacobiSVD per jacobian of an (M, 6, n) stack.

time_parameterization:
  TimeParameterization:
    compute: >-
      TOTG, ISP, constant-TCP and Ruckig scale with trajectory length. Only reads env, so no
      Environment event callback fires inside it.

urdf:
  module:
    parseURDFString: >-
      XML parsing plus mesh loading. A Python ResourceLocator re-acquires the GIL through its
      trampoline.
    parseURDFFile: See parseURDFString.

geometry:
  module:
    writeSignedDistanceFieldVDB: >-
      Encodes the whole grid; the field is discretized first with the GIL held, because a sampler
      may be Python, so the released region is pure C++.
    writeSignedDistanceFieldNVDB: See writeSignedDistanceFieldVDB.
    createMeshFromPath: >-
      File IO plus assimp parsing, like parseURDFFile; milliseconds per mesh (gil-hotspots).
    createConvexMeshFromPath: See createMeshFromPath; plus a convex hull.
    createMeshFromResource: >-
      See createMeshFromPath. A Python Resource re-acquires the GIL through its trampoline, and
      nanobind's shared_ptr deleter for it takes the GIL itself.
    createConvexMeshFromResource: See createMeshFromResource; plus a convex hull.

serialization:
  module:
    environment_to_xml: >-
      Serializes the whole command history under the environment's lock (see
      environment.Environment.init): seconds for a mesh-heavy scene.
    environment_to_binary: See environment_to_xml.
    environment_to_file: See environment_to_xml; the file is written without the GIL too.
    environment_from_xml: >-
      Replays the command history into a new Environment (seconds); it has no callbacks yet.
    environment_from_binary: See environment_from_xml.
    environment_from_file: See environment_from_xml; plus file IO.
    composite_instruction_to_file: File IO on the already serialized text (serialized with the GIL).
    scene_state_to_file: See composite_instruction_to_file.
    task_composer_log_to_file: See composite_instruction_to_file.
    composite_instruction_from_file: File IO, then parsing into a new object no other thread sees.
    scene_state_from_file: See composite_instruction_from_file.
    task_composer_log_from_file: See composite_instruction_from_file.

collision:
  DiscreteContactManager:
    contactTest: Broad and narrow phase over every enabled object; called in loops.
    setCollisionObjectsTransform: >-
      The transform-map overload updates every listed object's broad-phase AABB (gh-241). The
      (ids, (K, 4, 4) array) overload does the same for K objects: with every pose changed,
      0.1-0.15 ms at K = 80 and 21-24 ms at K = 1000 (Bullet, macOS arm64, 2026-11-21). It checks
      the array and copies it into C++ poses with the GIL held, then releases it.
  ContinuousContactManager:
    contactTest: See DiscreteContactManager.contactTest; swept volumes are costlier still.
    setCollisionObjectsTransform: See DiscreteContactManager.setCollisionObjectsTransform.
  ConvexDecomposition:
    compute: VHACD convex decomposition takes seconds per mesh.
  module:
    collideImplicitSDF: >-
      Multi-start descent: many distance and gradient evaluations per call. It solves on copies
      of the shapes and config, made with the GIL held and destroyed after it is re-acquired, so
      assigning a shape's members during the call affects only later calls, and the copies keep a
      shape's geometry alive. A Python distance, gradient or field sampler takes the GIL per call.

environment:
  Environment:
    init: >-
      Takes the environment's unique lock and fires event callbacks under its shared lock; a thread
      waiting for that lock with the GIL would deadlock against a Python callback
      (docs/developer/threading.md, Environment event callbacks). Builds the scene: 0.9 s.
    isInitialized: Takes the environment's shared lock; see init.
    reset: See init.
    clear: Takes the environment's unique lock; see init.
    getRevision: See isInitialized.
    getInitRevision: See isInitialized.
    getTimestamp: See isInitialized.
    getCurrentStateTimestamp: See isInitialized.
    getName: See isInitialized.
    setName: See clear.
    getSceneGraph: See isInitialized.
    getState: See isInitialized; the overloads that solve a new state cost a state solve.
    link_transforms_batch: >-
      Forward kinematics over every row of a joint-value array into a buffer allocated before the
      release; validation reads the environment, so it runs inside the release too.
    setState: See init (fires SCENE_STATE_CHANGED).
    addEventCallback: >-
      The registration takes the unique lock; the callable is wrapped first, with the GIL.
    removeEventCallback: See clear.
    clearEventCallbacks: See clear.
    applyCommand: See init; mesh-heavy links build collision geometry for seconds.
    applyCommands: See applyCommand.
    getCommandHistory: See isInitialized.
    getStateSolver: See isInitialized.
    getJointIds: See isInitialized.
    getActiveJointIds: See isInitialized.
    getLinkIds: See isInitialized.
    getActiveLinkIds: See isInitialized.
    getStaticLinkIds: See isInitialized.
    getRootLinkId: See isInitialized.
    getCurrentJointValues: See isInitialized.
    getLinkTransform: See isInitialized.
    getRelativeLinkTransform: See isInitialized.
    getLinkTransforms: See isInitialized.
    getCurrentFloatingJointValues: See isInitialized.
    getJointLimits: See isInitialized.
    getLinkCollisionEnabled: See isInitialized.
    getLinkVisibility: See isInitialized.
    getContactManagersPluginInfo: See isInitialized.
    getLink: See isInitialized.
    getJoint: See isInitialized.
    getGroupNames: See isInitialized.
    getGroupJointIds: See isInitialized.
    getJointGroup: See isInitialized.
    getKinematicGroup: See isInitialized; loads the IK plugin on first use (0.5-0.8 s).
    findTCPOffset: See isInitialized; a Python find-TCP callback takes the GIL itself.
    addFindTCPOffsetCallback: See addEventCallback.
    getDiscreteContactManager: See isInitialized; builds every collision shape on first use.
    getContinuousContactManager: See getDiscreteContactManager.
    setActiveDiscreteContactManager: See clear.
    setActiveContinuousContactManager: See clear.
    clearCachedDiscreteContactManager: See clear.
    clearCachedContinuousContactManager: See clear.
    getAllowedCollisionMatrix: See isInitialized.
    getCollisionMarginData: See isInitialized.
    setResourceLocator: See clear.
    getResourceLocator: See isInitialized.
    getKinematicsInformation: See isInitialized.
    clone: Deep copy under the shared lock (gh-134); see isInitialized.
    bind_value_equality: __eq__ / __ne__ hold a shared lock on the left operand's mutex.
  module:
    checkTrajectory: Collision-checks every state of a trajectory; can run for seconds.
    checkTrajectorySegment: One continuous check; called in loops.
    checkTrajectoryState: One discrete check; called in loops.
    _find_tcp_offset_on_native_thread: >-
      Private test oracle (gh-183): joins a native thread that must take the GIL itself.

common:
  module:
    removeLogRecordHandler: >-
      Mandatory, not a speed-up: upstream waits for the handler's in-flight calls on other threads,
      which need the GIL to run a Python handler, so holding it here deadlocks.

Measured candidates

pixi run gil-hotspots recorded the benchmarks and the full test suite on 2026-10-24 (macOS arm64, Python 3.14, 100 Hz, recorded at commit 903fedc, before the releases below). The table shows every unlisted binding above roughly 50 µs per call that had at least 10 GIL-held samples (100 ms) in either run, plus the decision. Below 10 samples the per-call mean is noise: one sample is 10 ms.

Binding Mean per call Calls Run Decision
serialization: environment_from_file 3.6 s 1 tests released: replays commands into a new Environment, which has no callbacks yet
serialization: environment_to_file 2.2 s 1 tests released: reads under the shared lock, as clone() does
serialization: environment_{to,from}_{xml,binary} 12.2 s together - tests released: same reasons (to and from share a test line, so no per-call mean)
motion_planners_simple: generateInterpolatedProgram 106 ms 37 tests released: interpolation and a state solve per step; only reads env
geometry: createMeshFromResource 2.5 ms 69 tests released, with the Path loaders and the ConvexMesh variants: file IO plus assimp, like parseURDFFile
environment: Environment.init 0.85 s / 0.93 s 303 / 438 bench / tests released, with every Environment method (event callbacks below)
environment: Environment.getKinematicGroup 0.83 s / 0.54 s 35 / 146 bench / tests released, with every Environment method
task_composer: TaskComposerPluginFactory.createTaskComposerNode 26 ms / 1.6 s 570 / 338 bench / tests GIL-held: unsynchronised factory cache
task_composer: TaskComposerPluginFactory.createTaskComposerExecutor 0.73 s / 0.99 s 2 / 48 bench / tests GIL-held: unsynchronised factory cache
kinematics: KinematicsPluginFactory.createFwdKin / createInvKin 0.92 s / 0.46 s 19 / 12 tests GIL-held: unsynchronised factory cache
collision: ContactManagersPluginFactory.createDiscreteContactManager / createContinuousContactManager 0.50 s / 0.56 s 22 / 17 tests GIL-held: unsynchronised factory cache
motion_planners_descartes: DescartesMoveProfileD.createKinematicGroup 0.96 s 3 tests released: it locks the environment, as every binding that reads one now does without the GIL
motion_planners_trajopt_ifopt: TrajOptIfoptCompositeProfile.create 84 ms 5 tests GIL-held: the binding runs Python-side contract checks around a trampoline
task_composer: TaskComposerPluginFactory.getAvailableTaskComposerNodePlugins 410 ms 2 tests GIL-held: a getter
geometry: PolygonMesh.getVertices / getFaces 80 µs 1257 tests GIL-held: getters (the cost is copying to NumPy)

setCollisionObjectsTransform(ids, transforms) with a (K, 4, 4) array was judged without a gil-hotspots run (py-spy needs sudo on macOS): timed directly with every pose changed per call, Bullet takes 0.1-0.15 ms at K = 80 and 21-24 ms at K = 1000 (macOS arm64, loaded machine, 2026-11-21), above the rule's 50 µs. It validates and copies the array into C++ poses with the GIL held, then releases it for upstream's (ids, poses) call, as the map overload does.

In the benchmarks, 90% of GIL-held samples fall in unlisted bindings, and over 99% of those are Environment.init, Environment.getKinematicGroup and the task composer factory. In real workloads, the remaining GIL-bound time is the Environment follow-up and the factory caches.

Finding candidates

The list was compiled by reading code. To measure instead, pixi run gil-hotspots (scripts/gil_hotspots.py) records the benchmarks, then the test suite, with py-spy record --gil and prints the bindings ranked by the time they hold the GIL. --gil keeps only samples of the thread holding it, so a binding that already releases it drops out. Benchmarks come first: test timings are dominated by setup.

py-spy samples time but can't count calls or name a nanobind function. So the same run loads scripts/gil_call_counts.py, a pytest plugin that counts every binding call by the Python line it comes from (sys.monitoring CALL events). A sample whose innermost Python frame is such a line is time inside that binding: the binding runs below the line, and a Python callback it calls has its own frame. Native frames (--native, Linux x86_64 and Windows only) aren't needed, so it runs on macOS too. py-spy attaches to the pytest process and asks for sudo on macOS, and on Linux unless kernel.yama.ptrace_scope=0. Failing tests still yield a complete profile: the task reports every run, then exits non-zero and names the runs that had failures.

Limits, all visible in the table:

  • Two bindings called on one line share a row, with no per-call mean.
  • Python work on a binding's line (building its arguments) counts toward that binding.
  • A subprocess started without the plugin (python -c ... in a test) is sampled but unnamed.
  • py-spy pauses the process for each sample, so timeout-bound tests can fail under it (test_constraint_not_linked did, once).

Read the calling line before acting on a row, then judge each candidate above roughly 50 µs per call against the rule. python scripts/gil_hotspots.py report build/gil-hotspots/*.txt re-ranks a recording, for instance after the list changed.

Tests

  • tests/audit/test_audit_gil.py: the audit's contract, on a fixture TU with one binding per release form and per non-release that must not count.
  • tests/test_gil_entry_points.py: run-time checks of the releases #124 added, of calcManipulabilityVolume_each and of the contact managers' setCollisionObjectsTransform(ids, transforms) stack overload. The oracle sets a switch interval far above the test's run time, so the main thread can only run while a worker is inside the call if the call dropped the GIL. The worker repeats the call until the main thread has run, so a fast call is still caught. A call that holds the GIL fails deterministically.
  • tests/test_gil_hotspots.py: the hotspot report's attribution rules on py-spy's raw format, and the call counter on a real binding.
  • tests/tesseract_motion_planners/test_trajopt_ifopt_planner.py (_TASK_COMPOSER_RELEASE): a Python composite profile and a Python cost run on the task composer's worker threads while the main thread waits on the future. Without the release in TaskComposerFuture.wait this deadlocks.

Environment event callbacks

Environment fires its event callbacks under a shared lock on its mutex, on the thread that changed it, after dropping the unique lock it applied the change under. A Python callback then waits for the GIL while that shared lock is held. A thread that waited for the environment's lock while holding the GIL would deadlock against it: a writer (setState, applyCommand, ...) always, a reader too on platforms whose shared mutex queues readers behind a waiting writer.

So no binding waits for an environment's lock with the GIL held:

  • every Environment method runs with the GIL released (NoGil in environment.cpp), its validation included: validation reads the environment, and its errors are plain C++ exceptions, translated once the GIL is back;
  • every binding in another module that reads an environment does the same: assignCurrentStateAsSeed, formatProgram, toToolpath, the Descartes profile create* methods, the TrajOpt-Ifopt profile create methods, createCollisionConstraints, the collision evaluators' constructors, the simple planner's instruction infos, and the serialization Environment functions;
  • PyEventCallbackFn and PyFindTCPOffsetFn hold their callable through gil_safe_object (tesseract_nb.h), so addEventCallback and Environment::clone copy them without the GIL, and each call takes the GIL itself.

A callback receives the event over its own copy of the history or state, so it may keep it. A callback must not change its environment: upstream holds the shared lock while it runs.

Test: tests/tesseract_environment/test_environment_lifetimes.py (test_event_callback_with_concurrent_writer_does_not_deadlock, a child interpreter with a timeout).

C++ threads that call Python at interpreter exit

A thread CPython didn't start, such as an executor worker running a Python log record handler, can be inside Python when the interpreter finalizes. Every call that takes the GIL then ends it: PyGILState_Ensure, PyEval_RestoreThread, and any Python code, since the eval loop gives the GIL away and takes it back. What "ends" means depends on the version and platform:

3.9–3.13 3.14+
Linux (glibc) pthread_exit: forced unwinding runs the thread's C++ destructors and catch (...) blocks the thread hangs
macOS pthread_exit, no C++ destructors run the thread hangs
Windows _endthreadex, no C++ destructors run the thread hangs

So on Linux before 3.14, a RAII guard on such a thread runs during that unwind, after CPython took its thread state away. nb::gil_scoped_acquire (and the PyGILState_Release in a nanobind override ticket) then aborts with PyGILState_Release: thread state ... must be current when releasing; a noexcept frame on the way terminates the process. CI hit this on Linux 3.12 only: macOS, Windows and 3.14 never run the destructors; the 3.13 jobs did not hit it in that run.

The rule for such a thread: while it is inside a call that may take the GIL, none of its frames owns a Python reference, a GIL guard or an override ticket, and none is noexcept. Call Python through the C API from plain functions (PyGILState_Ensure / PyGILState_Release by hand, PyObject_CallMethodObjArgs, raw references), and never drop a Python reference in a destructor. A thread ended mid-call leaves what it held allocated; Python is going away.

Log handlers and the task-composer server gate

Upstream calls each log record handler synchronously on the thread that logs, after the logger returns and with no tesseract lock held (logging.cpp dispatchHandlers). A Python handler on an executor worker therefore calls a TaskComposerServer like any other thread: while another thread reloads the server (loadConfig, addTask, addExecutor), it waits on the server gate with the GIL released. A handler called by the reloading thread itself is a call from inside the reload and raises TaskComposerServerBusyError. main's delivery thread, flushOutputHandlers() and the flush barrier that kept a reload from waiting for it went with the console_bridge API (0.36).

A reload waits for no handler's work, but it does not start while a call waits on the gate. A woken waiter has to take the GIL to see that the reload ended. A thread reloading in a loop keeps the GIL into its next reload unless the waiter has already waited a switch interval (5 ms) for it, and then the waiter sees that reload running and waits again. A worker's one log record could outlast dozens of reloads this way, and a run could take minutes. Anything between reloads that gives up the GIL or outlasts the switch interval hides it: a print, a time.sleep, or a slow GeneralResourceLocator() (70 ms in an editable install on the conda packages, 0.1 ms in a wheel). So a reload first waits for the calls already on the gate to take the GIL. That wait ends: they need nothing but the GIL, which the reload releases for it, and no reload starts until they are through, so a call waits for at most the one reload it found running.

A reload still holds the GIL throughout, except in the Python callbacks it makes. A handler on another thread that needs the GIL gets it at the next of those or between reloads, so each record logged during a reload can cost up to one reload.

The gate lives in the server (GatedServer, task_composer.cpp) and dies with it; a call keeps its server alive while it waits on the gate. The gate compensates for upstream's TaskComposerServer having no lock of its own (task_composer_server.h at 0.35.0).

Tests: tests/tesseract_task_composer/test_output_handler_deadlocks.py (TestServerReloadAgainstLogHandlers).

The viewer's player and viser's event loop

viser applies a browser's GUI update on its asyncio event loop: it sets the handle's value, then submits each plain on_update callback to its thread pool. GuiEvent carries no value, so the callback reads the handle back, and sees whatever another thread wrote in between. The viewer's player advances the time slider 30 times a second from its own thread. It used to check the slider and then write the next frame there, so a drag viser applied between the check and the write was overwritten, and playback paused at the player's time (Windows CI on f6006c83).

The player now checks and writes the slider in one call on viser's loop (ViserServer.get_event_loop(), public), ordered with viser's own writes: a drag that lands first fails the check, and its callback reads the drag back. The player waits at most VISER_LOOP_TIMEOUT_S for the loop. A call that has not started by then is cancelled before it can run (concurrent.futures.Future.set_running_or_notify_cancel), so a timeout leaves no late write.

Rule: a write from another thread to a viser GUI value that a browser also changes goes through viser's loop.

Tests: tests/viewer/test_viewer.py (test_drag_landing_mid_tick_is_not_overwritten, test_tick_on_a_wedged_viser_loop_writes_nothing).

Upstream: plugin factory caches

TaskComposerPluginFactory, KinematicsPluginFactory and ContactManagersPluginFactory each cache the plugin factories they load in a mutable std::map that their const create* methods fill without a mutex (task_composer_plugin_factory.cpp, kinematics_plugin_factory.h, contact_managers_plugin_factory.h at 0.35.0). Today the GIL serialises Python callers. Releasing it would let two threads that share a factory race on the map, which breaks rule 3. Their create* calls cost 0.03–1.6 s each, mostly plugin loading.

Upstream: task composer

  • TaskComposerServer has no lock: loadConfig / addTask / addExecutor race any other call on another thread. The binding's server gate serialises them (above).
  • TaskComposerExecutor has no wait-for-idle: Taskflow sets a run's future before it counts the run off its executor (tf::Executor::_tear_down_topology), and tf::Executor::wait_for_all is private to TaskflowTaskComposerExecutor. The exit drain (wait_for_in_flight_runs) therefore polls getTaskCount() every millisecond (EXIT_DRAIN_IDLE_POLL), only at interpreter exit and only for runs whose future is already set. A public waitForIdle() upstream would replace the poll with a wait.

Remaining work

Item Status Blocked on
List the Environment and environment-reading releases in scripts/nogil_entry_points.yaml incomplete the release-polish merge (the list lives outside the bindings)
Release the GIL in the plugin factories' create* methods incomplete a mutex around the factory caches upstream
Replace the exit drain's poll with a wait incomplete a public wait-for-idle on TaskComposerExecutor upstream

Free-threaded builds

The same annotations serve a free-threaded interpreter (#260): there, gil_scoped_release only detaches the thread state. In both builds, the real constraint on a binding is concurrent use of shared C++ objects.