doc: document the pool parameter in decorators

Signed-off-by: Matteo Cafasso <noxdafox@gmail.com>

doc/index.rst

@@ -33,6 +33,8 @@ Pebble aims to help managing threads and processes in an easier way. It wraps Py
 
    The *context* parameter can be used to specify the multiprocessing.context_ object used for starting the process.
 
+   The *pool* parameter accepts a pebble.ProcessPool_ object. If provided, the pool will be used to run the function instead of a dedicated process. The *name*, *daemon* and *context* parameters will be ignored.
+
 .. decorator:: concurrent.thread(name=None, daemon=True)
 
    Runs the decorated function in a concurrent thread, taking care of the results and error management.
@@ -43,6 +45,7 @@ Pebble aims to help managing threads and processes in an easier way. It wraps Py
 
    The *daemon* parameter switches between daemon and non-daemon threads.
 
+   The *pool* parameter accepts a pebble.ThreadPool_ object. If provided, the pool will be used to run the function instead of a dedicated thread. The *name* and *daemon* parameters will be ignored.
 
 `Asynchronous Module`
 ---------------------
@@ -61,6 +64,8 @@ Pebble aims to help managing threads and processes in an easier way. It wraps Py
 
    The *context* parameter can be used to specify the multiprocessing.context_ object used for starting the process.
 
+   The *pool* parameter accepts a pebble.ProcessPool_ object. If provided, the pool will be used to run the function instead of a dedicated process. The *name*, *daemon* and *context* parameters will be ignored.
+
 .. decorator:: asynchronous.thread(name=None, daemon=True)
 
    Runs the decorated function in a concurrent thread, taking care of the results and error management.
@@ -71,6 +76,8 @@ Pebble aims to help managing threads and processes in an easier way. It wraps Py
 
    The *daemon* parameter switches between daemon and non-daemon threads.
 
+   The *pool* parameter accepts a pebble.ThreadPool_ object. If provided, the pool will be used to run the function instead of a dedicated thread. The *name* and *daemon* parameters will be ignored.
+
 
 `Pebble Module`
 ---------------
@@ -474,6 +481,27 @@ If a `timeout` is provided, it will be applied to the whole chunk and not to the
 
         assert list(future.result()) == elements
 
+The `concurrent` and `asynchronous` decorators accept a *pool* parameter. This is useful to control how many instances of decorated functions can be run at the same time.
+
+::
+
+    from concurrent.futures import wait
+    from pebble import concurrent, ProcessPool
+
+    pool = ProcessPool(max_workers=4)
+
+    @concurrent.process(pool=pool)
+    def function(arg, kwarg=0):
+        return arg + kwarg
+
+    futures = []
+
+    # Maximum 4 executions of `function` will be executed in parallel
+    for _ in range(100):
+        futures.append(function(1, kwarg=1))
+
+    wait(futures)
+
 
 Pools and AsyncIO
 +++++++++++++++++