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:
- 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,==). - 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 thestd::functioncaster re-acquire the GIL themselves, as do the bindings' own callback wrappers and nanobind'sshared_ptrdeleter for a Python-owned object. - 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:
// 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.
# 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_linkeddid, 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, ofcalcManipulabilityVolume_eachand 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 inTaskComposerFuture.waitthis 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
Environmentmethod runs with the GIL released (NoGilinenvironment.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 profilecreate*methods, the TrajOpt-Ifopt profilecreatemethods,createCollisionConstraints, the collision evaluators' constructors, the simple planner's instruction infos, and theserializationEnvironment functions; PyEventCallbackFnandPyFindTCPOffsetFnhold their callable throughgil_safe_object(tesseract_nb.h), soaddEventCallbackandEnvironment::clonecopy 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¶
TaskComposerServerhas no lock: loadConfig / addTask / addExecutor race any other call on another thread. The binding's server gate serialises them (above).TaskComposerExecutorhas no wait-for-idle: Taskflow sets a run's future before it counts the run off its executor (tf::Executor::_tear_down_topology), andtf::Executor::wait_for_allis private toTaskflowTaskComposerExecutor. The exit drain (wait_for_in_flight_runs) therefore pollsgetTaskCount()every millisecond (EXIT_DRAIN_IDLE_POLL), only at interpreter exit and only for runs whose future is already set. A publicwaitForIdle()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.