-
Notifications
You must be signed in to change notification settings - Fork 237
Expand file tree
/
Copy pathparallel.py
More file actions
344 lines (266 loc) · 15.1 KB
/
parallel.py
File metadata and controls
344 lines (266 loc) · 15.1 KB
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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
import sys
from contextlib import nullcontext
from math import ceil
from types import LambdaType
from typing import (
Callable,
TYPE_CHECKING,
Generator,
Optional,
overload,
TypeVar,
Union,
)
if TYPE_CHECKING: # pragma: no cover
from docarray.typing import T
from docarray import Document, DocumentArray
from multiprocessing.pool import ThreadPool, Pool
T_DA = TypeVar('T_DA')
class ParallelMixin:
"""Helper functions that provide parallel map to :class:`DocumentArray`"""
# overload_inject_start_apply
@overload
def apply(
self: 'T',
func: Callable[['Document'], 'Document'],
backend: str = 'thread',
num_worker: Optional[int] = None,
show_progress: bool = False,
pool: Optional[Union['Pool', 'ThreadPool']] = None,
) -> 'T':
"""Apply ``func`` to every Document in itself, return itself after modification.
:param func: a function that takes :class:`Document` as input and outputs :class:`Document`.
:param backend: `thread` for multi-threading and `process` for multi-processing. Defaults to `thread`.
In general, if your
``func`` is IO-bound then `thread` is a good choice. If your ``func`` is CPU-bound, then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backend passes the variable via pickle and works in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param pool: use an existing/external process or thread pool. If given, `backend` is ignored and you will be responsible for closing the pool.
:param show_progress: show a progress bar
"""
# overload_inject_end_apply
def apply(self: 'T', *args, **kwargs) -> 'T':
# implementation_stub_inject_start_apply
"""Apply ``func`` to every Document in itself, return itself after modification.
:param func: a function that takes :class:`Document` as input and outputs :class:`Document`.
:param backend: `thread` for multi-threading and `process` for multi-processing. Defaults to `thread`.
In general, if your
``func`` is IO-bound then `thread` is a good choice. If your ``func`` is CPU-bound, then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backend passes the variable via pickle and works in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param pool: use an existing/external process or thread pool. If given, `backend` is ignored and you will be responsible for closing the pool.
:param show_progress: show a progress bar
:return: itself after modification
.. # noqa: DAR102
.. # noqa: DAR202
.. # noqa: DAR101
.. # noqa: DAR003
"""
# implementation_stub_inject_end_apply
for doc in self.map(*args, **kwargs):
self[doc.id] = doc
return self
def map(
self,
func: Callable[['Document'], 'T'],
backend: str = 'thread',
num_worker: Optional[int] = None,
show_progress: bool = False,
pool: Optional[Union['Pool', 'ThreadPool']] = None,
) -> Generator['T', None, None]:
"""Return an iterator that applies function to every **element** of iterable in parallel, yielding the results.
.. seealso::
- To process on a batch of elements, please use :meth:`.map_batch`;
- To return a :class:`DocumentArray`, please use :meth:`.apply`.
:param func: a function that takes :class:`Document` as input and outputs anything. You can either modify elements
in-place (only with `thread` backend) or work later on return elements.
:param backend: `thread` for multi-threading and `process` for multi-processing. Defaults to `thread`.
In general, if your
``func`` is IO-bound then `thread` is a good choice. If your ``func`` is CPU-bound, then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backing passes the variable via pickle and works in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param show_progress: show a progress bar
:param pool: use an existing/external process or thread pool. If given, `backend` is ignored and you will be responsible for closing the pool.
:yield: anything return from ``func``
"""
if _is_lambda_or_partial_or_local_function(func) and backend == 'process':
func = _globalize_lambda_function(func)
from rich.progress import track
if pool:
p = pool
ctx_p = nullcontext()
else:
p = _get_pool(backend, num_worker)
ctx_p = p
with ctx_p:
for x in track(
p.imap(func, self), total=len(self), disable=not show_progress
):
yield x
# overload_inject_start_apply_batch
@overload
def apply_batch(
self: 'T',
func: Callable[['DocumentArray'], 'DocumentArray'],
batch_size: int,
backend: str = 'thread',
num_worker: Optional[int] = None,
shuffle: bool = False,
show_progress: bool = False,
pool: Optional[Union['Pool', 'ThreadPool']] = None,
) -> 'T':
"""Batches itself into mini-batches, applies `func` to every mini-batch, and return itself after the modifications.
EXAMPLE USAGE
.. code-block:: python
from docarray import Document, DocumentArray
da = DocumentArray([Document(text='The cake is a lie') for _ in range(100)])
def func(doc):
da.texts = [t.upper() for t in da.texts]
return da
da.apply_batch(func, batch_size=10)
print(da.texts[:3])
.. code-block:: text
['THE CAKE IS A LIE', 'THE CAKE IS A LIE', 'THE CAKE IS A LIE']
:param func: a function that takes :class:`DocumentArray` as input and outputs :class:`DocumentArray`.
:param backend: `thread` for multi-threading and `process` for multi-processing. Defaults to `thread`.
In general, if your
``func`` is IO-bound then `thread` is a good choice. If your ``func`` is CPU-bound, then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backend passes the variable via pickle and works in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param batch_size: Size of each generated batch (except the last batch, which might be smaller). Default: 32
:param shuffle: If set, shuffle the Documents before dividing into minibatches.
:param show_progress: show a progress bar
:param pool: use an existing/external process or thread pool. If given, `backend` is ignored and you will be responsible for closing the pool.
"""
# overload_inject_end_apply_batch
def apply_batch(self: 'T', *args, **kwargs) -> 'T':
# implementation_stub_inject_start_apply_batch
"""Batches itself into mini-batches, applies `func` to every mini-batch, and return itself after the modifications.
EXAMPLE USAGE
.. code-block:: python
from docarray import Document, DocumentArray
da = DocumentArray([Document(text='The cake is a lie') for _ in range(100)])
def func(doc):
da.texts = [t.upper() for t in da.texts]
return da
da.apply_batch(func, batch_size=10)
print(da.texts[:3])
.. code-block:: text
['THE CAKE IS A LIE', 'THE CAKE IS A LIE', 'THE CAKE IS A LIE']
:param func: a function that takes :class:`DocumentArray` as input and outputs :class:`DocumentArray`.
:param backend: `thread` for multi-threading and `process` for multi-processing. Defaults to `thread`.
In general, if your
``func`` is IO-bound then `thread` is a good choice. If your ``func`` is CPU-bound, then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backend passes the variable via pickle and works in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param batch_size: Size of each generated batch (except the last batch, which might be smaller). Default: 32
:param shuffle: If set, shuffle the Documents before dividing into minibatches.
:param show_progress: show a progress bar
:param pool: use an existing/external process or thread pool. If given, `backend` is ignored and you will be responsible for closing the pool.
:return: itself after modification
.. # noqa: DAR102
.. # noqa: DAR202
.. # noqa: DAR101
.. # noqa: DAR003
"""
# implementation_stub_inject_end_apply_batch
for _b in self.map_batch(*args, **kwargs):
self[[doc.id for doc in _b]] = _b
return self
def map_batch(
self: 'T_DA',
func: Callable[['DocumentArray'], 'T'],
batch_size: int,
backend: str = 'thread',
num_worker: Optional[int] = None,
shuffle: bool = False,
show_progress: bool = False,
pool: Optional[Union['Pool', 'ThreadPool']] = None,
) -> Generator['T', None, None]:
"""Return an iterator that applies function to every **minibatch** of iterable in parallel, yielding the results.
Each element in the returned iterator is :class:`DocumentArray`.
.. seealso::
- To process single element, please use :meth:`.map`;
- To return :class:`DocumentArray`, please use :meth:`.apply_batch`.
:param batch_size: Size of each generated batch (except the last one, which might be smaller, default: 32)
:param shuffle: If set, shuffle the Documents before dividing into minibatches.
:param func: a function that takes :class:`DocumentArray` as input and outputs anything. You can either modify elements
in-place (only with `thread` backend) or work later on return elements.
:param backend: if to use multi-`process` or multi-`thread` as the parallelization backend. In general, if your
``func`` is IO-bound then perhaps `thread` is good enough. If your ``func`` is CPU-bound then you may use `process`.
In practice, you should try yourselves to figure out the best value. However, if you wish to modify the elements
in-place, regardless of IO/CPU-bound, you should always use `thread` backend.
.. warning::
When using `process` backend, you should not expect ``func`` modify elements in-place. This is because
the multiprocessing backing pass the variable via pickle and work in another process. The passed object
and the original object do **not** share the same memory.
:param num_worker: the number of parallel workers. If not given, then the number of CPUs in the system will be used.
:param show_progress: show a progress bar
:param pool: use an existing/external pool. If given, `backend` is ignored and you will be responsible for closing the pool.
:yield: anything return from ``func``
"""
if _is_lambda_or_partial_or_local_function(func) and backend == 'process':
func = _globalize_lambda_function(func)
from rich.progress import track
if pool:
p = pool
ctx_p = nullcontext()
else:
p = _get_pool(backend, num_worker)
ctx_p = p
with ctx_p:
for x in track(
p.imap(func, self.batch(batch_size=batch_size, shuffle=shuffle)),
total=ceil(len(self) / batch_size),
disable=not show_progress,
):
yield x
def _get_pool(backend, num_worker):
if backend == 'thread':
from multiprocessing.pool import ThreadPool as Pool
return Pool(processes=num_worker)
elif backend == 'process':
from multiprocessing.pool import Pool
return Pool(processes=num_worker)
else:
raise ValueError(
f'`backend` must be either `process` or `thread`, receiving {backend}'
)
def _is_lambda_or_partial_or_local_function(func):
return (
(isinstance(func, LambdaType) and func.__name__ == '<lambda>')
or not hasattr(func, '__qualname__')
or ('<locals>' in func.__qualname__)
)
def _globalize_lambda_function(func):
def result(*args, **kwargs):
return func(*args, **kwargs)
from docarray.helper import random_identity
result.__name__ = result.__qualname__ = random_identity()
setattr(sys.modules[result.__module__], result.__name__, result)
return result