Install & Compatibility
Where this runs
tested against v0.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KnockKnock
✓ from gilknocker import KnockKnock
✗ from gilknocker import Knocker
This example demonstrates how to use the `Knocker` class to measure GIL contention during the execution of a Python function. It initializes `Knocker` with recommended default intervals, starts the measurement, runs a simulated GIL-heavy function, stops the measurement, and then prints the collected metrics.
import time
from gilknocker import Knocker
def my_gil_heavy_function():
# Simulate some GIL-bound work
_ = [i*i for i in range(1_000_000)]
knocker = Knocker(
polling_interval_micros=1000, # How frequently to re-acquire GIL
sampling_interval_micros=10000, # How long to run polling routine
sleeping_interval_micros=100000 # How long to sleep between sampling
)
print("Starting GIL contention measurement...")
knocker.start()
my_gil_heavy_function()
knocker.stop()
print("Stopping GIL contention measurement.")
metrics = knocker.get_metrics()
print(f"Average GIL acquisition time: {metrics.avg_acquisition_time_micros:.2f} microseconds")
print(f"Max GIL acquisition time: {metrics.max_acquisition_time_micros:.2f} microseconds")
print(f"Total samples: {metrics.total_samples}")
Debug
Known issues
gotchaThe `polling_interval_micros` parameter directly impacts both the accuracy of the GIL contention measurement and the performance overhead introduced by `gilknocker`. Setting this value too low increases accuracy but can significantly slow down your program by increasing competition for the GIL. Users should experiment to find an appropriate balance, with `polling_interval_micros=1_000` often suggested as a reasonable starting point.fixAdjust `polling_interval_micros` and other interval parameters based on your application's sensitivity to overhead and the desired measurement granularity.
affects: All versions
gotcha`gilknocker` is designed for quick, specific GIL contention metrics within defined code blocks. It is not intended as a replacement for comprehensive profiling tools like `py-spy` or `cProfile` for general performance analysis, as it focuses solely on GIL activity rather than overall CPU or memory usage.fixFor holistic performance debugging, integrate `gilknocker` alongside broader profiling tools.
affects: All versions
gotchaThe Python Global Interpreter Lock (GIL) is an evolving part of CPython. Future versions of CPython (e.g., Python 3.13+) are exploring options to make the GIL optional (as proposed by PEP 703), and Python 3.12 introduced a per-interpreter GIL. If the GIL is eventually removed or its internal behavior changes significantly in future Python releases, `gilknocker`'s core functionality may be impacted or become obsolete, requiring updates to remain compatible or relevant.fixMonitor `gilknocker`'s release notes for compatibility updates with newer Python versions, especially those implementing GIL-related changes.
affects: Potentially future Python 3.13+ versions
Upgrade
Version history
0.4.2latest on PyPI · released Oct 18, 2025
Audit
Dependencies
No dependency data recorded yet.