| Name | ironfence JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | |
| Summary | Synchronization primitives specifically designed for use with Asyncio Coroutines, inspired by Rust. |
| upload_time | 2023-10-02 09:23:38 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
asyncio
mutex
rust
rwlock
synchronization
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# IronFence Python Library Documentation
## Introduction
IronFence is a Python library that provides two types of synchronization primitives: Mutex and RWLock. These objects allow you to protect shared data from concurrent access in an asynchronous environment. By using Mutex and RWLock, you can ensure that your application remains coroutine-safe and avoids race conditions[^1].
[^1]: IronFence doesn't protect against inter-process or intra-thread races. Use additional sync mechanisms like [multiprocessing.Lock](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Lock) or [threading.Lock](https://docs.python.org/3/library/threading.html#threading.Lock) for added protection.
## Installation
When pip is available, the distribution can be downloaded from PyPI and installed in one step:
```python
pip install ironfence
```
## Mutex
A `Mutex` (ashort for "mutual exclusion") is a synchronization primitive that allows only one coroutine to access a shared resource at a time. Other coroutines that attempt to acquire the lock will block until the current owner releases it.
```python
import asyncio
import ironfence
shared_state = {}
mu = ironfence.Mutex(shared_state)
async def modify_state():
print("modifying state..")
async with mu.lock() as value:
await asyncio.sleep(1)
value["key"] = "example"
print("State modified!")
async def read_state():
print("reading state..")
async with mu.lock() as value:
print("State is:", value)
# run concurrently
asyncio.get_event_loop().run_until_complete(
asyncio.gather(read_state(), modify_state(), read_state())
)
```
In this example, we create a Mutex instance named `mu` that guards a shared dictionary called `shared_state`. We define two coroutines, `modify_state()` and `read_state()`, that need to access `shared_state`. To ensure exclusive access, we use the `lock()` method of the Mutex object to acquire the lock before modifying or reading the shared data. The `lock()` method returns a context manager that automatically releases the lock when exiting the scope.
## RWLock
An `RWLock` (short for "reader-writer lock") is a synchronization primitive that allows multiple reader coroutines to access a shared resource simultaneously, while allowing only one writer coroutine to modify the resource at a time. This makes it more efficient than a `Mutex` in situations where there are many reader coroutines and only occasional writes.
```python
import asyncio
import ironfence
async def read_state(rw_lock):
async with rw_lock.read() as value:
print(value)
async def modify_state(rw_lock):
async with rw_lock.write() as value:
value.append("example")
async def main():
shared_state = []
rw_lock = ironfence.RWLock(shared_state)
await asyncio.gather(
read_state(rw_lock), modify_state(rw_lock), read_state(rw_lock)
)
asyncio.get_event_loop().run_until_complete(main())
```
In this example, we create an `RWLock` instance named `rw_lock` that guards a shared list called `shared_state`. We define two coroutines, `read_state()` and `modify_state()`, that need to access `shared_state`. To ensure exclusive access, we use the `read()` and `write()` methods of the `RWLock` object to acquire the appropriate locks. The `read()` method acquires a read lock, which allows multiple reader coroutines to enter, while the `write()` method acquires a write lock, which blocks all reader coroutines until the write operation completes.
Raw data
{
"_id": null,
"home_page": "",
"name": "ironfence",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "asyncio,mutex,rust,rwlock,synchronization",
"author": "",
"author_email": "ab0142 <120799552+ab0142@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/62/21/88f52eb33fa496fa9a3f6fc999ca5d6db680ee5c5636f59e592b575dea74/ironfence-0.1.0.tar.gz",
"platform": null,
"description": "# IronFence Python Library Documentation\n\n## Introduction\n\nIronFence is a Python library that provides two types of synchronization primitives: Mutex and RWLock. These objects allow you to protect shared data from concurrent access in an asynchronous environment. By using Mutex and RWLock, you can ensure that your application remains coroutine-safe and avoids race conditions[^1].\n\n[^1]: IronFence doesn't protect against inter-process or intra-thread races. Use additional sync mechanisms like [multiprocessing.Lock](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Lock) or [threading.Lock](https://docs.python.org/3/library/threading.html#threading.Lock) for added protection.\n\n## Installation\n\nWhen pip is available, the distribution can be downloaded from PyPI and installed in one step:\n\n```python\npip install ironfence\n```\n\n## Mutex\n\nA `Mutex` (ashort for \"mutual exclusion\") is a synchronization primitive that allows only one coroutine to access a shared resource at a time. Other coroutines that attempt to acquire the lock will block until the current owner releases it.\n\n```python\nimport asyncio\n\nimport ironfence\n\nshared_state = {}\nmu = ironfence.Mutex(shared_state)\n\n\nasync def modify_state():\n print(\"modifying state..\")\n async with mu.lock() as value:\n await asyncio.sleep(1)\n value[\"key\"] = \"example\"\n print(\"State modified!\")\n\n\nasync def read_state():\n print(\"reading state..\")\n async with mu.lock() as value:\n print(\"State is:\", value)\n\n\n# run concurrently\nasyncio.get_event_loop().run_until_complete(\n asyncio.gather(read_state(), modify_state(), read_state())\n)\n```\n\nIn this example, we create a Mutex instance named `mu` that guards a shared dictionary called `shared_state`. We define two coroutines, `modify_state()` and `read_state()`, that need to access `shared_state`. To ensure exclusive access, we use the `lock()` method of the Mutex object to acquire the lock before modifying or reading the shared data. The `lock()` method returns a context manager that automatically releases the lock when exiting the scope.\n\n\n## RWLock\n\nAn `RWLock` (short for \"reader-writer lock\") is a synchronization primitive that allows multiple reader coroutines to access a shared resource simultaneously, while allowing only one writer coroutine to modify the resource at a time. This makes it more efficient than a `Mutex` in situations where there are many reader coroutines and only occasional writes.\n\n```python\nimport asyncio\n\nimport ironfence\n\n\nasync def read_state(rw_lock):\n async with rw_lock.read() as value:\n print(value)\n\n\nasync def modify_state(rw_lock):\n async with rw_lock.write() as value:\n value.append(\"example\")\n\n\nasync def main():\n shared_state = []\n rw_lock = ironfence.RWLock(shared_state)\n await asyncio.gather(\n read_state(rw_lock), modify_state(rw_lock), read_state(rw_lock)\n )\n\n\nasyncio.get_event_loop().run_until_complete(main())\n```\n\nIn this example, we create an `RWLock` instance named `rw_lock` that guards a shared list called `shared_state`. We define two coroutines, `read_state()` and `modify_state()`, that need to access `shared_state`. To ensure exclusive access, we use the `read()` and `write()` methods of the `RWLock` object to acquire the appropriate locks. The `read()` method acquires a read lock, which allows multiple reader coroutines to enter, while the `write()` method acquires a write lock, which blocks all reader coroutines until the write operation completes.\n",
"bugtrack_url": null,
"license": "",
"summary": "Synchronization primitives specifically designed for use with Asyncio Coroutines, inspired by Rust.",
"version": "0.1.0",
"project_urls": {
"repository": "https://github.com/ab0142/ironfence"
},
"split_keywords": [
"asyncio",
"mutex",
"rust",
"rwlock",
"synchronization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "75809a9f0a48f58a1dae661bd8e095af5a6eb49a315e01e5e788a885be16b0a0",
"md5": "934a2685ccb749cce04ab99ecf8b92c3",
"sha256": "ddb36406f23118bbca76445bae01e5d34ed6afd60aba9e35551e298134712d53"
},
"downloads": -1,
"filename": "ironfence-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "934a2685ccb749cce04ab99ecf8b92c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4893,
"upload_time": "2023-10-02T09:23:37",
"upload_time_iso_8601": "2023-10-02T09:23:37.233478Z",
"url": "https://files.pythonhosted.org/packages/75/80/9a9f0a48f58a1dae661bd8e095af5a6eb49a315e01e5e788a885be16b0a0/ironfence-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "622188f52eb33fa496fa9a3f6fc999ca5d6db680ee5c5636f59e592b575dea74",
"md5": "031d22dc4e6ee37a33d96977ac6c3882",
"sha256": "7b0d7bcd5d9e378bcc63071c354e073a39eb266974563997b049d227d51a4156"
},
"downloads": -1,
"filename": "ironfence-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "031d22dc4e6ee37a33d96977ac6c3882",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7189,
"upload_time": "2023-10-02T09:23:38",
"upload_time_iso_8601": "2023-10-02T09:23:38.354709Z",
"url": "https://files.pythonhosted.org/packages/62/21/88f52eb33fa496fa9a3f6fc999ca5d6db680ee5c5636f59e592b575dea74/ironfence-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-02 09:23:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ab0142",
"github_project": "ironfence",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ironfence"
}
