.. image:: assets/lox_200w.png

.. image:: https://img.shields.io/pypi/v/lox.svg :target: https://pypi.python.org/pypi/lox

.. image:: https://circleci.com/gh/BrianPugh/lox.svg?style=svg :target: https://circleci.com/gh/BrianPugh/lox

.. image:: https://readthedocs.org/projects/lox/badge/?version=latest :target: https://lox.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

Threading and multiprocessing made easy.

• Free software: Apache-2.0 license
• Documentation: https://lox.readthedocs.io.
• Python >=3.6

Lox provides decorators and synchronization primitives to quickly add concurrency to your projects.

pip3 install --user lox

• Multithreading: Powerful, intuitive multithreading in just 2 additional lines of code.

• Multiprocessing: Truly parallel function execution with the same interface as multithreading.

• Synchronization: Advanced thread synchronization, communication, and resource management tools.

• All objects except lox.process are for threads. These will eventually be multiprocess friendly.

Easy Multithreading ^^^^^^^^^^^^^^^^^^^

>>> import lox
>>>
>>> @lox.thread(4) # Will operate with a maximum of 4 threads
... def foo(x,y):
...     return x*y
>>> foo(3,4) # normal function calls still work
12
>>> for i in range(5):
...     foo.scatter(i, i+1)
-ignore-
>>> # foo is currently being executed in 4 threads
>>> results = foo.gather() # block until results are ready
>>> print(results) # Results are in the same order as scatter() calls
[0, 2, 6, 12, 20]

Or, for example, if you aren't allowed to directly decorate the function you would like multithreaded/multiprocessed, you can just directly invoke the decorator:

.. code-block:: pycon

>>> # Lets say we don't have direct access to this function
... def foo(x, y):
...     return x * y
...
>>>
>>> def my_func():
...     foo_threaded = lox.thread(foo)
...     for i in range(5):
...         foo_threaded.scatter(i, i + 1)
...     results = foo_threaded.gather()
...     # foo is currently being executed in default 50 thread executor pool
...     return results
...

This also makes it easier to dynamically control the number of thread/processes in the executor pool. The syntax is a little weird, but this is just explicitly invoking a decorator that has optional arguments:

.. code-block:: pycon

>>> # Set the number of executer threads to 10
>>> foo_threaded = lox.thread(10)(foo)

Easy Multiprocessing ^^^^^^^^^^^^^^^^^^^^

.. code-block:: pycon

>>> import lox
>>>
>>> @lox.process(4)  # Will operate with a pool of 4 processes
... def foo(x, y):
...     return x * y
...
>>> foo(3, 4)  # normal function calls still work
12
>>> for i in range(5):
...     foo.scatter(i, i + 1)
...
-ignore-
>>> # foo is currently being executed in 4 processes
>>> results = foo.gather()  # block until results are ready
>>> print(results)  # Results are in the same order as scatter() calls
[0, 2, 6, 12, 20]

Progress Bar Support (tqdm) ^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: pycon

>>> import lox
>>> from random import random
>>> from time import sleep
>>>
>>> @lox.thread(2)
... def foo(multiplier):
...     sleep(multiplier * random())
...
>>> for i in range(10):
>>>     foo.scatter(i)
>>> results = foo.gather(tqdm=True)
90%|████████████████████████████████▌        | 9/10 [00:03<00:00,  1.32it/s]
100%|███████████████████████████████████████| 10/10 [00:06<00:00,  1.46s/it]