Metadata-Version: 2.4
Name: whatamithinking-aiotools
Version: 1.0.1
Summary: asyncio tools
Author-email: Connor Sherwood Maynes <connormaynes@gmail.com>
Project-URL: Homepage, https://github.com/whatamithinking/aiotools
Keywords: asyncio
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Provides-Extra: test
Dynamic: license-file

---
header-includes:
    - \usepackage{enumitem}
    - \setlistdepth{20}
    - \renewlist{itemize}{itemize}{20}
    - \renewlist{enumerate}{enumerate}{20}
    - \setlist[itemize]{label=$\cdot$}
    - \setlist[itemize,1]{label=\textbullet}
    - \setlist[itemize,2]{label=--}
    - \setlist[itemize,3]{label=*}
    - \usepackage{fvextra}
	- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}

output:
    rmarkdown::pdf_document:
        keep_tex: yes
---

## WhatAmIThinking-aiotools

asyncio tools

## Table of Contents

<!-- TOC -->

- [WhatAmIThinking-aiotools](#whatamithinking-aiotools)
- [Table of Contents](#table-of-contents)
- [Shields](#shields)
  - [Problems](#problems)
  - [Solutions](#solutions)
- [Locks](#locks)
  - [Problems](#problems-1)
  - [Solutions](#solutions-1)

<!-- /TOC -->

## Shields

### Problems

The built-in `asyncio.shield()` function has the following issues:

- if the current task is cancelled, execution flow will continue but the shielded task will keep running in the background, making program flow difficult to debug and buggy in cases where resources needed by that task are destroyed after that task completes, creating a sort of race condition.
    - the solution of wrapping the task you are running within a task works but is inefficient and slow because you have to wait for a cycle of the loop before you can get your result back
- code has to be awkwardly chopped up into blocks, because some parts may need to be shielded while others should not be.
    - there is no solution to this using the stdlib alone, except to break into multiple functions which is awkward and hard to follow

### Solutions

Use `shield_scope()` context manager to shield blocks of code from execution
The task cancellation is delayed until the scope exits, after which `asyncio.CancelledError` will be raised on the next `await`

Use `asyncio.get_event_loop().set_task_factory(aiotools.create_shieldable_task)` to enable shielding to work properly. This works by creating a custom python asyncio task class.

## Locks

### Problems

- Cannot re-enter `asyncio.Lock`
    - code has to instead be awkwardly chopped up to avoid re-entering the same lock and getting deadlocked. this again is hard to follow.

### Solutions

Use `RLock` which is just a subclass of `asyncio.Lock` with support for re-entrance
