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.

Claude Code skill

The matching Claude Code skill is published in skills/. Copy that directory to your local skills directory:

git clone https://github.com/XuNeo/hwlock.git
cp -R hwlock/skills ~/.claude/skills/hwlock

The skill instructs hardware workflows to use hwlock and to run pip install hwlock when the command is not installed.

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