Metadata-Version: 2.1
Name: mpilock
Version: 1.0.0
Summary: Synchronize read/write access to resources shared between MPI processes.
Home-page: https://github.com/Helveg/zwembad
Author: Robin De Schepper
Author-email: robingilbert.deschepper@unipv.it
License: UNKNOWN
Keywords: mpi pool mpipool zwembad
Platform: UNKNOWN
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.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy (>=1.20.0)
Requires-Dist: mpi4py (>=3.0.3)

[![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 perform `read`, `write` or `single_write`.

Read operations happen in parallel while write operations will lock the resource and
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.

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()
```


