1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
.. _aiojobs-quickstart:
Quickstart
==========
.. currentmodule:: aiojobs
The library gives controlled way for scheduling background tasks.
Installation
-------------
Install the library:
.. code-block:: bash
$ pip3 install aiojobs
Simple example
----------------
The library API is pretty minimalistic: make a scheduler, spawn jobs,
close scheduler.
Instantiate a scheduler::
import aiojobs
scheduler = aiojobs.Scheduler()
Spawn a new job::
await scheduler.spawn(coro())
At the end of program gracefully close the scheduler::
await scheduler.wait_and_close()
Let's collect it altogether into very small but still functional example::
import asyncio
import aiojobs
async def coro(timeout):
await asyncio.sleep(timeout)
async def main():
async with aiojobs.Scheduler() as scheduler:
for i in range(100):
# spawn jobs
await scheduler.spawn(coro(i/10))
await asyncio.sleep(5.0)
# not all scheduled jobs are finished at the moment
# Exit from context will gracefully wait on tasks before closing
# any remaining spawned jobs
asyncio.run(main())
Our jobs are very simple :func:`asyncio.sleep` calls with variable
timeout -- pretty enough for demonstration.
Example schedules ``100`` jobs, every job takes from ``0`` to ``10``
seconds for its execution.
Next we waits for ``5`` seconds. Roughly half of scheduled jobs should
be finished already but ``50`` jobs are still active.
For closing them we exit the context manager, which calls
:meth:`aiojobs.Scheduler.wait_and_close`. This waits for a grace period
to allow tasks to complete normally, then after a timeout it sends
:exc:`asyncio.CancelledError` into every non-closed job to stop them.
Alternatively, we could use :meth:`Scheduler.close` to immediately
close/cancel the jobs.
That's pretty much it.
Integration with aiohttp web server
-----------------------------------
.. currentmodule:: aiojobs.aiohttp
In aiohttp web-handlers might be cancelled at any time on client disconnection.
But sometimes user need to prevent unexpected cancellation of some
code executed by web handler.
Other use case is spawning background tasks like statistics update or
email sending and returning HTTP response as fast as possible.
Both needs could be solved by *aiojobs.aiohttp* integration module.
The library has two helpers: :func:`setup` for installing web
application initialization and finalization hooks and :func:`spawn`
for spawning new jobs:
.. code-block:: python
from aiohttp import web
from aiojobs.aiohttp import setup, spawn
import aiojobs
async def handler(request):
await spawn(request, coro())
return web.Response()
app = web.Application()
app.router.add_get('/', handler)
setup(app)
Future reading
--------------
For more info about library design and principles read :ref:`aiojobs-intro`.
API reference is here: :ref:`aiojobs-api`.
|
