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

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for neoxu from gravatar.com neoxu

Credits

Author: XuNeo

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

embedded hardware jtag lock mutex queue serial

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hwlock-0.1.0.tar.gz (16.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hwlock-0.1.0-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file hwlock-0.1.0.tar.gz.

File metadata

  • Download URL: hwlock-0.1.0.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hwlock-0.1.0.tar.gz
Algorithm Hash digest
SHA256 7a229b92c4c0b9fc4eaa64145282045b00691e5e1022030057388a5b747eda74
MD5 b76e2eb48be8f992c525193f332a4906
BLAKE2b-256 6f7b89b446223db9775aba55858dc9121d85b2405b7e7b4b90d1459f7d40f2c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for hwlock-0.1.0.tar.gz:

Publisher: publish.yml on XuNeo/hwlock

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hwlock-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: hwlock-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 8.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hwlock-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 81debe865c10736bb875c6470f068ddffe3c60ec0e2b016e21a06fc9328de110
MD5 8afc755eb274279f99c5ae12a43cddf8
BLAKE2b-256 7dd1e77bf3a6fd207f54f2243b3dc7f7e7fac2161fd5583e56aee3a043f4411e

See more details on using hashes here.

Provenance

The following attestation bundles were made for hwlock-0.1.0-py3-none-any.whl:

Publisher: publish.yml on XuNeo/hwlock

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page