hwlock

Coordinate exclusive access to a physical hardware resource shared by multiple local processes. hwlock provides a cooperative mutex with a priority-aware FIFO queue for development boards, serial consoles, JTAG probes, programmers, and similar one-at-a-time resources.

It is daemon-free and dependency-free: state is stored in files and guarded with flock.

Requirements

• Linux or another POSIX host with Python 3.10+
• All resource users must cooperate by running their hardware operation through hwlock

Install

python3 -m pip install hwlock

Usage

Run a command while holding a resource lock:

hwlock exec --resource g2-proto --label firmware-flash -- ./flash.sh

exec waits for the resource, runs the command, propagates its exit status, and releases the lock afterward.

For workflows that span several commands, acquire and release a lease explicitly:

hwlock acquire --resource g2-proto --label debug-session
# use the board
hwlock release --resource g2-proto --label debug-session

The same label is required to release a lease, preventing one user from accidentally releasing another user's lock.

Inspect current use and queues:

hwlock status
hwlock status --resource g2-proto
hwlock list

Use high priority for urgent recovery work. It moves ahead of queued normal-priority waiters but never interrupts the current holder:

hwlock exec --resource g2-proto --label recovery \
  --priority high --timeout 120 -- ./recover.sh

Clear a leaked lease only after confirming that no hardware operation is still running:

hwlock force-release --resource g2-proto

Commands

• acquire: wait for and retain a lease until a matching release
• release: release a lease held by the same label
• exec: hold the resource for the lifetime of a command
• status: show holders and queued waiters
• list: list known resources
• force-release: clear holder metadata without checking its owner

Run hwlock <command> --help for command-specific options.

State

State defaults to ~/.cache/hwlock. Set HWLOCK_STATE_DIR to isolate a different coordination domain:

HWLOCK_STATE_DIR=/tmp/team-hwlock hwlock status

Locks coordinate processes on one host only. They do not prevent access from other machines or programs that bypass hwlock.

Development

python3 -m pip install -e '.[dev]'
pytest -q
python3 -m build

Release

Pushing a tag matching v* runs .github/workflows/publish.yml. The workflow builds the distributions and publishes them to PyPI using trusted publishing; it does not store a PyPI API token.

Configure the PyPI trusted publisher with:

• PyPI project: hwlock
• GitHub owner: XuNeo
• Repository: hwlock
• Workflow: publish.yml
• Environment: pypi

License

MIT