Metadata-Version: 2.4
Name: mpilock
Version: 2.1.0
Summary: Synchronize read/write access to resources shared between MPI processes.
Keywords: mpi,pool,lock,synchronization
Author-email: Robin De Schepper <robin@alexandria.sc>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: BSD License
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
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: mpi4py>=3.0.0
Requires-Dist: opentelemetry-api>=1.0.0
Project-URL: Homepage, https://github.com/Helveg/mpilock

[![codecov](https://codecov.io/gh/Helveg/mpilock/branch/main/graph/badge.svg?token=WQ1U6UNPGA)](https://codecov.io/gh/Helveg/mpilock)

# About

`mpilock` offers a `WindowController` class with a high-level API for parallel access to
resources. The `WindowController` can be used to synchronize MPI processes during `read`,
`write` or `single_write` operations on shared resources.

Read operations happen in parallel while write operations will lock the resource,
prevent any new read or write operations, and will wait for all existing read operations to
finish. After the write operation completes, the lock is released and other operations can
resume.

> [!IMPORTANT]
>
> One of the MPI ranks involved will need to act as the root. Under some conditions, for some
> MPI implementations, whenever the root rank acquires a read lock, others may not be able to
> acquire a read or write lock in parallel. This applies to you if:
>   * The root rank acquires read locks
>   * You use an affected MPI implementation
>   * Your root rank does not perform MPI operations while it holds the read lock.
>
> A solution to this is to frequently call an MPI noop like `Iprobe()` from the root rank while
> it holds the read lock.

The `WindowController` does not contain any logic to control the resources, it only locks
and synchronizes the MPI processes. Once the operation permission is obtained, it's up to
the user to perform the reading/writing to the resources.

The `sync` method is a factory for `WindowController`s and can simplify creation of
`WindowController`s.

# Example usage

```python
from mpilock import sync
from h5py import File

# Create a default WindowController on `COMM_WORLD` with the master on rank 0
ctrl = sync()

# Fencing is the preferred idiom to fence anyone that isn't writing out of
# the writer's code block, and afterwards share a resource
with ctrl.single_write() as fence:
    # Makes anyone without access long jump to the end of the with statement
    fence.guard()
    resource = h5py.File("hello.world", "w")
    # Put a resource to be collected by other processes
    fence.share(resource)
resource = fence.collect()

try:
    # Acquire a parallel read lock, guarantees noone writes while you're reading.
    with ctrl.read():
        data = resource["/my_data"][()]
    # Acquire a write lock, will block all reading and writing.
    with ctrl.write():
        resource.create_dataset(lock.rank, data=data)
finally:
    with ctrl.single_write() as fence:
        fence.guard()
        resource.close()

# The window controller itself needs to be closed as well (is done atexit)
ctrl.close()
```

