Skip to content

fix: Handle thread/process affinity when freeing objects#285

Merged
tmathern merged 8 commits into
mainfrom
mathern/defend-threads
Jun 15, 2026
Merged

fix: Handle thread/process affinity when freeing objects#285
tmathern merged 8 commits into
mainfrom
mathern/defend-threads

Conversation

@tmathern

@tmathern tmathern commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Context

The C2PA native library the Python SDK relies on (C FFI) uses a process-global pointer registry to track and free allocated pointers. That registry is guarded by a lock. When a Python process forks, that lock can be inherited in a locked state with no surviving thread to release it, so the next free in the child deadlocks. Some Python stacks do exactly that (using forks), setting up this case.

Changes

This PR stamps each wrapper with the PID that created it. Only the owning process can therefore free its very own memory during a garbage collector run (whenever the gc decides to run). A forked child skips the native free entirely (those objects belong to the parent anyway, the child should not even try to free those). Objects the child creates itself free normally, since their are "owned" by the right process/PID.

Additional details

Some Python stacks call os.fork() under the hood. When a process calls fork(), the child starts as a near-exact copy of the parent's memory. But... threads are the exception: only the thread that called fork() exists in the child. Every other thread is simply gone, never to be seen again and therefore not able to interact with the newly created flow.
Then, remember that the native library keeps the pointer registry behind a mutex (c2pa_c_ffi, get_registry, oncelock). If a thread was holding that mutex at the moment of the fork, the child inherits it locked, with no other surviving thread to release it since the things have now been "disconnected". The next time the child want to clean up a native object/handle/pointer, and that can happen when Python's garbage collector run whenever it sees fit (and call the deleters), it blocks on that mutex forever.
A native registry-side fix in the C FFI would mean a pthread_atfork child handler that correctly resets the lock, but that's POSIX-only... And it would only clear the deadlock situation, not decide ownership: which inherited objects the child may touch is something only the language binding has the context to know, which is what this change helps decide (the PID stamping)!

Verifications

Benchmark results for scenarios capable of encountering the issue (all new scenarios added by this PR):
Note: Having a report already means it could run to end and did not deadlock.

Screenshot 2026-06-11 at 14 22 20 Screenshot 2026-06-11 at 14 22 45 Screenshot 2026-06-11 at 14 23 16 Screenshot 2026-06-11 at 14 23 36 Screenshot 2026-06-11 at 14 23 50 Screenshot 2026-06-11 at 14 24 16 Screenshot 2026-06-11 at 14 24 37

Checklist

  • This PR represents a single feature, fix, or change.
  • All applicable changes have been documented.
  • Any TO DO items (or similar) have been entered as GitHub issues and the link to that issue has been included in a comment.

@tmathern tmathern self-assigned this Jun 11, 2026
@tmathern tmathern marked this pull request as ready for review June 12, 2026 14:27
@tmathern tmathern changed the title fix: Handle thread affinity when freeing objects fix: Handle thread/process affinity when freeing objects Jun 12, 2026
@tmathern tmathern requested review from andrewhalle and ok-nick June 12, 2026 21:03

@andrewhalle andrewhalle left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought about this a lot and discussed with Tania and I think this is a good solution. Calling fork() when there are multiple active threads triggers a DeprecationWarning on python 3.12+ (see discussion for details), so callers will probably be forced to deal with this correctly at some point. In the meantime, this change makes these functions fork-safe, and the usual case is memory space of the child process will be quickly replaced by an exec anyway, or else it will exit.

@tmathern tmathern merged commit 572eec5 into main Jun 15, 2026
26 checks passed
@tmathern tmathern deleted the mathern/defend-threads branch June 15, 2026 17:52
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.

3 participants