Metadata-Version: 2.4
Name: hwlock
Version: 0.1.0
Summary: Coordinate exclusive access to shared physical hardware resources.
Project-URL: Homepage, https://github.com/XuNeo/hwlock
Project-URL: Repository, https://github.com/XuNeo/hwlock
Project-URL: Issues, https://github.com/XuNeo/hwlock/issues
Author: XuNeo
License-Expression: MIT
License-File: LICENSE
Keywords: embedded,hardware,jtag,lock,mutex,queue,serial
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
python3 -m pip install hwlock
```

## Usage

Run a command while holding a resource lock:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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
