gilknocker

What it is and what it does

GIL Knocker is a lightweight, quick-and-dirty GIL contention profiler for Python. It works by spawning a background thread that repeatedly tries to acquire the GIL at configurable intervals and measures how long each acquisition takes; longer acquisition times indicate higher contention. The contention metric is a float between 0 and 1 representing roughly how busy the GIL was during the sampling window.

The package is designed for developers who want to quickly check GIL contention within a specific code section without the overhead of a full profiler like py-spy. It exposes three tunable parameters—polling_interval_micros, sampling_interval_micros, and sleeping_interval_micros—to trade off accuracy against performance impact. The monitoring thread runs in the background and can be started, stopped, and queried for the current contention metric; the metric persists after stop() is called.

Use it for:

• Identify whether a slow code section is GIL-bound or CPU-bound by measuring contention during execution.
• Quick profiling of multi-threaded Python code to spot lock contention without running a full external profiler.
• Benchmark the impact of GIL-heavy operations on concurrent workloads by sampling contention before and after code changes.
• Monitor GIL contention in production or test environments with minimal overhead by tuning polling intervals.
• Validate that async or C-extension refactoring actually reduced GIL pressure in a specific code path.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Measures GIL contention within a specific code block by spawning a monitoring thread that periodically attempts to re-acquire the GIL and records acquisition latency as a contention metric.

Yes, if you need a lightweight, inline GIL contention check for a specific code block and are willing to verify the license. The package has no runtime dependencies, installs cleanly on common platforms, and aligns with py-spy's measurements. However, verify the license status before use in proprietary projects, and be aware that the project is aging (300 days since last release) with modest maintenance activity.

Install

gilknocker on PyPI

pip install gilknocker

uv add gilknocker

poetry add gilknocker

Installing gilknocker

Before you install

Medium install friction due to compiled wheels for multiple platforms and Python versions (3.10, 3.11+). No runtime dependencies. Last release 300 days ago; repository is active but aging, with modest maintenance signals.

License in practice

License status is unclear—no SPDX identifier or raw license text provided. Verify licensing before use in proprietary or copyleft-sensitive projects.

Quickstart

from gilknocker import KnockKnock

knocker = KnockKnock(1_000)
knocker.start()

# ... code to measure ...

metric = knocker.contention_metric  # float 0–1
knocker.stop()

Requires Python >= 3.9. Compiled extension; installation depends on wheel availability for your platform.

Verify before relying

• Whether the license is open-source, proprietary, or dual-licensed—no license metadata is present in the package.
• Accuracy and overhead of the contention metric compared to py-spy or other profilers in production workloads.
• Support for Python versions beyond 3.11 (wheels shown only for 3.10 and 3.11).

Package facts

Evidence: gilknocker-0.4.2-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_aarch64.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_armv7l.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_i686.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_ppc64le.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_s390x.whl; gilknocker-0.4.2-cp310-cp310-manylinux_2_24_x86_64.whl; gilknocker-0.4.2-cp310-cp310-win32.whl; gilknocker-0.4.2-cp310-cp310-win_amd64.whl; gilknocker-0.4.2-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_24_aarch64.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_24_armv7l.whl; gilknocker-0.4.2-cp311-cp311-manylinux_2_24_i686.whl

Keywords: GIL

Tags

More Monitoring packages