fix: Protect native handles from concurrent access using locks

.github/workflows/threading-benchmark.yml

@@ -0,0 +1,52 @@
+name: Python SDK threading checks
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - labeled
+
+permissions:
+  contents: read
+
+jobs:
+  threading-benchmark:
+    name: Python SDK threading checks
+    runs-on: ubuntu-24.04-arm
+    # Backstop: In case there is a hang.
+    timeout-minutes: 20
+    if: |
+      contains(github.event.pull_request.labels.*.name, 'check-threading-benchmark') &&
+      (
+        github.event.pull_request.author_association == 'COLLABORATOR' ||
+        github.event.pull_request.author_association == 'MEMBER' ||
+        github.event.pull_request.author_association == 'OWNER'
+      )
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build perf image
+        run: make perf-image
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Make sure crashes would be reported.
+      - name: Check the harness can detect failures
+        run: make threading-bench-self-test
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run thread-safety invariants
+        run: make threading-bench
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload failure logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: threading-invariant-logs
+          path: tests/perf/reports/*-threads.log
+          if-no-files-found: ignore

.gitignore

@@ -126,3 +126,6 @@ src/c2pa/libs/
 # Memory profiling reports
 tests/perf/reports/*.html
 tests/perf/reports/*.bin
+
+# Threading failure logs
+tests/perf/reports/*.log

Makefile

@@ -172,3 +172,25 @@ memory-use-bench:
 clean-memory-perf-reports:
 	rm -f tests/perf/reports/*.html tests/perf/reports/*.bin
 	@echo "Cleared tests/perf/reports/"
+
+# Thread-safety invariants (runs in Docker, same image as the memory benchmark)
+# More details for usage are in tests/perf/README.md
+THREAD_ROUNDS ?= 20
+
+# Checks that the harness itself reports crashes, hangs and plain exceptions
+# correctly. A harness that cannot see a failure is indistinguishable from a
+# passing run, so this gates the real suite rather than documenting it.
+.PHONY: threading-bench-self-test
+threading-bench-self-test: perf-image
+	docker run --rm -v $(PWD):/workspace -e PYTHONPATH=/workspace/src -e GITHUB_TOKEN c2pa-memray-$(PERF_ENV) python -m tests.perf.run_thread_profile --self-test
+
+# Runs the thread-safety invariant scenarios. Pre-requisite: Docker image built
+# using `make perf-image` (or `perf-image-rebuild`).
+.PHONY: threading-bench
+threading-bench: threading-bench-self-test
+	docker run --rm -v $(PWD):/workspace $(GH_SUMMARY_MOUNT) -e PYTHONPATH=/workspace/src -e PERF_ENV=$(PERF_ENV) -e THREAD_ROUNDS=$(THREAD_ROUNDS) -e THREAD_HANG_TIMEOUT -e GITHUB_TOKEN -e GITHUB_STEP_SUMMARY c2pa-memray-$(PERF_ENV) python -m tests.perf.run_thread_profile $(SCENARIO_ARG) $(PERF_ARGS)
+
+.PHONY: clean-threading-reports
+clean-threading-reports:
+	rm -f tests/perf/reports/*-threads.log
+	@echo "Cleared tests/perf/reports/*-threads.log"

docs/context-settings.md

@@ -752,6 +752,8 @@ ctx = Context()
 assert isinstance(ctx, ContextProvider)  # True
 ```
 
+A provider that does not derive from `ManagedResource` runs without in-flight teardown protection. `Reader` and `Builder` check `is_valid` before use, but nothing defers a teardown that arrives mid-construction, so closing such a provider on another thread while a `Reader` or `Builder` is being built from it can free the native context while that construction is still using it. The built-in `Context` carries that protection. Custom providers that share a context across threads should keep it alive for the duration of any construction that uses it.
+
 ## Migrating from load_settings
 
 The `load_settings()` function is deprecated. Replace it with `Settings` and `Context` APIs: