Metadata-Version: 2.3
Name: numba-cache-lock
Version: 0.1.0a2
Summary: A caching system for Numba with file locking support
Keywords: numba,caching
Author: Guilherme Leobas
Requires-Python: >=3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: flufl-lock (>=8.2.0,<9.0.0)
Requires-Dist: numba
Project-URL: Home, https://github.com/Quansight/numba-cache-lock
Project-URL: Source, https://github.com/Quansight/numba-cache-lock
Description-Content-Type: text/markdown

# numba-lock-cache

A Python package that monkey-patches Numba's caching mechanism to safely coordinate concurrent cache access using file locks.

## Why?

Numba’s function-level caching (`@jit(cache=True)`) is not concurrency-safe by default. This can lead to:

- Crashes when multiple processes load/write to the same cache
- Especially problematic on shared filesystems (e.g., NFS)

## Locking Mechanism

- Uses [`flufl.lock`](https://pypi.org/project/flufl.lock/) for file-based locking.
- Lock file is created next to the cache index file:
  `/path/to/cache/func.nbi.lock`
- Lock behavior:
  - Timeout to acquire: 60 minutes (configurable)
  - Lifetime: `None` (lock persists until released)
  - NFS-safe: relies on atomic file creation

## Installation

```bash
pip install numba-lock-cache
```

## How to use it

Just import the patch Numba in your application:

```python
import numba_cache_lock

numba_cache_lock.patch_numba_cache()

from numba import jit

@jit(cache=True)
def my_func(x):
    return x * 2
```

By default, `patch_numba_cache` will hold a lock for 1 hour in the worst case.
One can change this value by assigning the `lifetime=` keyword argument to a
`timedelta` object.

