# `multiprocessing` --- Process-based parallelism

Code source : Lib/multiprocessing/

Disponibilité: not Android, not iOS, not WASI.

This module is not supported on mobile platforms or WebAssembly platforms.

## Introduction

`multiprocessing` is a package that supports spawning processes using an API similar to the `threading` module. The `multiprocessing` package offers both local and remote concurrency, effectively side-stepping the Global Interpreter Lock by using subprocesses instead of threads. Due to this, the `multiprocessing` module allows the programmer to fully leverage multiple processors on a given machine. It runs on both POSIX and Windows.

The `multiprocessing` module also introduces the `Pool` object which offers a convenient means of parallelizing the execution of a function across multiple input values, distributing the input data across processes (data parallelism). The following example demonstrates the common practice of defining such functions in a module so that child processes can successfully import that module. This basic example of data parallelism using `Pool`,

    from multiprocessing import Pool

    def f(x):
        return x*x

    if __name__ == '__main__':
        with Pool(5) as p:
            print(p.map(f, [1, 2, 3]))

affiche sur la sortie standard

    [1, 4, 9]

The `multiprocessing` module also introduces APIs which do not have analogs in the `threading` module, like the ability to `terminate`, `interrupt` or `kill` a running process.

Voir aussi

`concurrent.futures.ProcessPoolExecutor` offers a higher level interface to push tasks to a background process without blocking execution of the calling process. Compared to using the `Pool` interface directly, the `concurrent.futures` API more readily allows the submission of work to the underlying process pool to be separated from waiting for the results.

### La classe `Process`

In `multiprocessing`, processes are spawned by creating a `Process` object and then calling its `start()` method. `Process` follows the API of `threading.Thread`. A trivial example of a multiprocess program is

    from multiprocessing import Process

    def f(name):
        print('hello', name)

    if __name__ == '__main__':
        p = Process(target=f, args=('bob',))
        p.start()
        p.join()

Voici un exemple plus étoffé qui affiche les identifiants des processus créés :

    from multiprocessing import Process
    import os

    def info(title):
        print(title)
        print('module name:', __name__)
        print('parent process:', os.getppid())
        print('process id:', os.getpid())

    def f(name):
        info('function f')
        print('hello', name)

    if __name__ == '__main__':
        info('main line')
        p = Process(target=f, args=('bob',))
        p.start()
        p.join()

La nécessité de la ligne `if __name__ == '__main__'` est expliquée dans la section Lignes directrices de programmation.

The arguments to `Process` usually need to be picklable so they can be passed to the child process. If you tried typing the above example directly into a REPL it could lead to an `AttributeError` in the child process trying to locate the f function in the `__main__` module.

### Contextes et méthodes de démarrage

Depending on the platform, `multiprocessing` supports three ways to start a process. These start methods are

> spawn

>   The parent process starts a fresh Python interpreter process. The child process will only inherit those resources necessary to run the process object's `run()` method. In particular, unnecessary file descriptors and handles from the parent process will not be inherited. Starting a process using this method is rather slow compared to using fork or forkserver.

>   Available on POSIX and Windows platforms. The default on Windows and macOS.

> fork

>   Le processus parent utilise `os.fork()` pour forker l'interpréteur Python. Le processus fils, quand il démarre, est effectivement identique au processus parent. Toutes les ressources du parent sont héritées par le fils. Notez qu'il est problématique de forker sans danger un processus multi-threadé.

>   Available on POSIX systems.

>   Modifié dans la version 3.14: This is no longer the default start method on any platform. Code that requires fork must explicitly specify that via `get_context()` or `set_start_method()`.

>   Modifié dans la version 3.12: If Python is able to detect that your process has multiple threads, the `os.fork()` function that this start method calls internally will raise a `DeprecationWarning`. Use a different start method. See the `os.fork()` documentation for further explanation.

> forkserver

>   When the program starts and selects the forkserver start method, a server process is spawned. From then on, whenever a new process is needed, the parent process connects to the server and requests that it fork a new process. The fork server process is single threaded unless system libraries or preloaded imports spawn threads as a side-effect so it is generally safe for it to use `os.fork()`. No unnecessary resources are inherited.

>   Available on POSIX platforms which support passing file descriptors over Unix pipes such as Linux. The default on those.

>   Modifié dans la version 3.14: This became the default start method on POSIX platforms.

Modifié dans la version 3.4: spawn added on all POSIX platforms, and forkserver added for some POSIX platforms. Child processes no longer inherit all of the parents inheritable handles on Windows.

Modifié dans la version 3.8: On macOS, the spawn start method is now the default. The fork start method should be considered unsafe as it can lead to crashes of the subprocess as macOS system libraries may start threads. See bpo-33725.

Modifié dans la version 3.14: On POSIX platforms the default start method was changed from fork to forkserver to retain the performance but avoid common multithreaded process incompatibilities. See gh-84559.

On POSIX using the spawn or forkserver start methods will also start a resource tracker process which tracks the unlinked named system resources (such as named semaphores or `SharedMemory` objects) created by processes of the program. When all processes have exited the resource tracker unlinks any remaining tracked object. Usually there should be none, but if a process was killed by a signal there may be some "leaked" resources. (Neither leaked semaphores nor shared memory segments will be automatically unlinked until the next reboot. This is problematic for both objects because the system allows only a limited number of named semaphores, and shared memory segments occupy some space in the main memory.)

Pour sélectionner une méthode de démarrage, utilisez la fonction `set_start_method()` dans la clause `if __name__ == '__main__'` du module principal. Par exemple :

    import multiprocessing as mp

    def foo(q):
        q.put('hello')

    if __name__ == '__main__':
        mp.set_start_method('spawn')
        q = mp.Queue()
        p = mp.Process(target=foo, args=(q,))
        p.start()
        print(q.get())
        p.join()

`set_start_method()` ne doit pas être utilisée plus d'une fois dans le programme.

Alternativement, vous pouvez utiliser `get_context()` pour obtenir un contexte. Les contextes ont la même API que le module multiprocessing, et permettent l'utilisation de plusieurs méthodes de démarrage dans un même programme.

    import multiprocessing as mp

    def foo(q):
        q.put('hello')

    if __name__ == '__main__':
        ctx = mp.get_context('spawn')
        q = ctx.Queue()
        p = ctx.Process(target=foo, args=(q,))
        p.start()
        print(q.get())
        p.join()

Notez que les objets relatifs à un contexte ne sont pas forcément compatibles avec les processus d'un contexte différent. En particulier, les verrous créés avec le contexte fork ne peuvent pas être passés aux processus lancés avec les méthodes spawn ou forkserver.

Libraries using `multiprocessing` or `ProcessPoolExecutor` should be designed to allow their users to provide their own multiprocessing context. Using a specific context of your own within a library can lead to incompatibilities with the rest of the library user's application. Always document if your library requires a specific start method.

Avertissement

The `'spawn'` and `'forkserver'` start methods generally cannot be used with "frozen" executables (i.e., binaries produced by packages like PyInstaller and cx_Freeze) on POSIX systems. The `'fork'` start method may work if code does not use threads.

### Échange d'objets entre les processus

`multiprocessing` supports two types of communication channel between processes:

Files (queues)

> La classe `Queue` est un clone assez proche de `queue.Queue`. Par exemple :

>     from multiprocessing import Process, Queue

>     def f(q):
>         q.put([42, None, 'hello'])

>     if __name__ == '__main__':
>         q = Queue()
>         p = Process(target=f, args=(q,))
>         p.start()
>         print(q.get())    # prints "[42, None, 'hello']"
>         p.join()

> Queues are thread and process safe. Any object put into a `multiprocessing` queue will be serialized.

Tubes (pipes)

> La fonction `Pipe()` renvoie une paire d'objets de connexion connectés à un tube qui est par défaut duplex (à double sens). Par exemple :

>     from multiprocessing import Process, Pipe

>     def f(conn):
>         conn.send([42, None, 'hello'])
>         conn.close()

>     if __name__ == '__main__':
>         parent_conn, child_conn = Pipe()
>         p = Process(target=f, args=(child_conn,))
>         p.start()
>         print(parent_conn.recv())   # prints "[42, None, 'hello']"
>         p.join()

> Les deux objets de connexion renvoyés par `Pipe()` représentent les deux extrémités d'un tube. Chaque objet de connexion possède (entre autres) des méthodes `send()` et `recv()`. Notez que les données d'un tube peuvent être corrompues si deux processus (ou fils d'exécution) essaient de lire ou d'écrire sur la même extrémité du tube en même temps. Bien évidemment, deux processus peuvent utiliser les deux extrémités différentes en même temps sans risque de corruption.

> The `send()` method serializes the object and `recv()` re-creates the object.

### Synchronisation entre processus

`multiprocessing` contains equivalents of all the synchronization primitives from `threading`. For instance one can use a lock to ensure that only one process prints to standard output at a time:

    from multiprocessing import Process, Lock

    def f(l, i):
        l.acquire()
        try:
            print('hello world', i)
        finally:
            l.release()

    if __name__ == '__main__':
        lock = Lock()

        for num in range(10):
            Process(target=f, args=(lock, num)).start()

Sans le verrou, les sorties des différents processus risquent d'être mélangées.

### Partager un état entre les processus

Comme mentionné plus haut, il est généralement préférable d'éviter autant que possible d'utiliser des états partagés en programmation concurrente. C'est particulièrement vrai quand plusieurs processus sont utilisés.

However, if you really do need to use some shared data then `multiprocessing` provides a couple of ways of doing so.

Mémoire partagée

> Les données peuvent être stockées dans une mémoire partagée en utilisant des `Value` ou des `Array`. Par exemple, le code suivant

>     from multiprocessing import Process, Value, Array

>     def f(n, a):
>         n.value = 3.1415927
>         for i in range(len(a)):
>             a[i] = -a[i]

>     if __name__ == '__main__':
>         num = Value('d', 0.0)
>         arr = Array('i', range(10))

>         p = Process(target=f, args=(num, arr))
>         p.start()
>         p.join()

>         print(num.value)
>         print(arr[:])

> affiche

>     3.1415927
>     [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

> Les arguments `'d'` et `'i'` utilisés à la création des `num` et `arr` sont des codes de types identiques à ceux du module `array` : `'d'` indique un flottant double-précision et `'i'` indique un entier signé. Ces objets peuvent être partagés sans problème entre processus ou fils d’exécution.

> Pour plus de flexibilité dans l'utilisation de mémoire partagée, vous pouvez utiliser le module `multiprocessing.sharedctypes` qui permet la création d'objets arbitraires ctypes alloués depuis la mémoire partagée.

Processus serveur

> Un objet gestionnaire renvoyé par `Manager()` contrôle un processus serveur qui détient les objets Python et autorise les autres processus à les manipuler à l'aide de mandataires.

> A manager returned by `Manager()` will support types `list`, `dict`, `set`, `Namespace`, `Lock`, `RLock`, `Semaphore`, `BoundedSemaphore`, `Condition`, `Event`, `Barrier`, `Queue`, `Value` and `Array`. For example,

>     from multiprocessing import Process, Manager

>     def f(d, l, s):
>         d[1] = '1'
>         d['2'] = 2
>         d[0.25] = None
>         l.reverse()
>         s.add('a')
>         s.add('b')

>     if __name__ == '__main__':
>         with Manager() as manager:
>             d = manager.dict()
>             l = manager.list(range(10))
>             s = manager.set()

>             p = Process(target=f, args=(d, l, s))
>             p.start()
>             p.join()

>             print(d)
>             print(l)
>             print(s)

> affiche

>     {0.25: None, 1: '1', '2': 2}
>     [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
>     {'a', 'b'}

> Les processus serveurs de gestionnaires sont plus flexibles que les mémoires partagées parce qu'ils peuvent gérer des types d'objets arbitraires. Aussi, un gestionnaire unique peut être partagé par les processus sur différentes machines à travers le réseau. Cependant, ils sont plus lents que les mémoires partagées.

### Utiliser un pool de workers

La classe `Pool` représente un pool de processus de travail. Elle possède des méthodes qui permettent aux tâches d'être déchargées vers les processus de travail de différentes manières.

Par exemple :

    from multiprocessing import Pool, TimeoutError
    import time
    import os

    def f(x):
        return x*x

    if __name__ == '__main__':
        # start 4 worker processes
        with Pool(processes=4) as pool:

            # print "[0, 1, 4,..., 81]"
            print(pool.map(f, range(10)))

            # print same numbers in arbitrary order
            for i in pool.imap_unordered(f, range(10)):
                print(i)

            # evaluate "f(20)" asynchronously
            res = pool.apply_async(f, (20,))      # runs in *only* one process
            print(res.get(timeout=1))             # prints "400"

            # evaluate "os.getpid()" asynchronously
            res = pool.apply_async(os.getpid, ()) # runs in *only* one process
            print(res.get(timeout=1))             # prints the PID of that process

            # launching multiple evaluations asynchronously *may* use more processes
            multiple_results = [pool.apply_async(os.getpid, ()) for i in range(4)]
            print([res.get(timeout=1) for res in multiple_results])

            # make a single worker sleep for 10 seconds
            res = pool.apply_async(time.sleep, (10,))
            try:
                print(res.get(timeout=1))
            except TimeoutError:
                print("We lacked patience and got a multiprocessing.TimeoutError")

            print("For the moment, the pool remains available for more work")

        # exiting the 'with'-block has stopped the pool
        print("Now the pool is closed and no longer available")

Notez que les méthodes d'un pool ne doivent être utilisées que par le processus qui l'a créée.

Note

Functionality within this package requires that the `__main__` module be importable by the children. This is covered in Lignes directrices de programmation however it is worth pointing out here. This means that some examples, such as the `multiprocessing.pool.Pool` examples will not work in the interactive interpreter. For example:

    >>> from multiprocessing import Pool
    >>> p = Pool(5)
    >>> def f(x):
    ...     return x*x
    ...
    >>> with p:
    ...     p.map(f, [1,2,3])
    Process PoolWorker-1:
    Process PoolWorker-2:
    Process PoolWorker-3:
    Traceback (most recent call last):
    Traceback (most recent call last):
    Traceback (most recent call last):
    AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>
    AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>
    AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>

Si vous essayez ce code, il affichera trois traces d'appels complètes entrelacées de manière semi-aléatoire, et vous devrez vous débrouiller pour arrêter le processus maître.

## Référence

The `multiprocessing` package mostly replicates the API of the `threading` module.

### Global start method

Python supports several ways to create and initialize a process. The global start method sets the default mechanism for creating a process.

Several multiprocessing functions and methods that may also instantiate certain objects will implicitly set the global start method to the system's default, if it hasn’t been set already. The global start method can only be set once. If you need to change the start method from the system default, you must proactively set the global start method before calling functions or methods, or creating these objects.

### `Process` et exceptions

class multiprocessing.Process(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None)

  Les objets process représentent une activité exécutée dans un processus séparé. La classe `Process` a des équivalents à toutes les méthodes de `threading.Thread`.

  The constructor should always be called with keyword arguments. group should always be `None`; it exists solely for compatibility with `threading.Thread`. target is the callable object to be invoked by the `run()` method. It defaults to `None`, meaning nothing is called. name is the process name (see `name` for more details). args is the argument tuple for the target invocation. kwargs is a dictionary of keyword arguments for the target invocation. If provided, the keyword-only daemon argument sets the process `daemon` flag to `True` or `False`. If `None` (the default), this flag will be inherited from the creating process.

  By default, no arguments are passed to target. The args argument, which defaults to `()`, can be used to specify a list or tuple of the arguments to pass to target.

  If a subclass overrides the constructor, it must make sure it invokes the base class constructor (`super().__init__()`) before doing anything else to the process.

  Note

  In general, all arguments to `Process` must be picklable. This is frequently observed when trying to create a `Process` or use a `concurrent.futures.ProcessPoolExecutor` from a REPL with a locally defined target function.

  Passing a callable object defined in the current REPL session causes the child process to die via an uncaught `AttributeError` exception when starting as target must have been defined within an importable module in order to be loaded during unpickling.

  Example of this uncatchable error from the child:

      >>> import multiprocessing as mp
      >>> def knigit():
      ...     print("Ni!")
      ...
      >>> process = mp.Process(target=knigit)
      >>> process.start()
      >>> Traceback (most recent call last):
        File ".../multiprocessing/spawn.py", line ..., in spawn_main
        File ".../multiprocessing/spawn.py", line ..., in _main
      AttributeError: module '__main__' has no attribute 'knigit'
      >>> process
      <SpawnProcess name='SpawnProcess-1' pid=379473 parent=378707 stopped exitcode=1>

  See Les méthodes de démarrage spawn et forkserver. While this restriction is not true if using the `"fork"` start method, as of Python `3.14` that is no longer the default on any platform. See Contextes et méthodes de démarrage. See also gh-132898.

  Modifié dans la version 3.3: Added the daemon parameter.

  run()

    Méthode représentant l'activité du processus.

    Vous pouvez redéfinir cette méthode dans une sous-classe. La méthode standard `run()` invoque l'objet appelable passé au constructeur comme argument target, si fourni, avec les arguments séquentiels et nommés respectivement pris depuis les paramètres args et kwargs.

    Using a list or tuple as the args argument passed to `Process` achieves the same effect.

    Example:

        >>> from multiprocessing import Process
        >>> p = Process(target=print, args=[1])
        >>> p.run()
        1
        >>> p = Process(target=print, args=(1,))
        >>> p.run()
        1

  start()

    Démarre l'activité du processus.

    Elle doit être appelée au plus une fois par objet processus. Elle s'arrange pour que la méthode `run()` de l'objet soit invoquée dans un processus séparé.

  join([timeout])

    Si l'argument optionnel timeout est `None` (par défaut), la méthode bloque jusqu'à ce que le processus dont la méthode `join()` a été appelée se termine. Si timeout est un nombre positif, elle bloque au maximum pendant timeout secondes. Notez que la méthode renvoie `None` si le processus se termine ou si le temps d'exécution expire. Vérifiez l'attribut `exitcode` du processus pour déterminer s'il s'est terminé.

    join peut être appelée plusieurs fois sur un même processus.

    Un processus ne peut pas s'attendre lui-même car cela causerait un interblocage. C'est une erreur d'essayer d'attendre un processus avant qu'il ne soit démarré.

  name

    Le nom du processus. Le nom est une chaîne de caractères utilisée uniquement pour l'identification du processus. Il n'a pas de sémantique. Plusieurs processus peuvent avoir le même nom.

    Le nom initial est déterminé par le constructeur. Si aucun nom explicite n'est fourni au constructeur, un nom de la forme « Process-N1:N2:...:Nk » est construit, où chaque Nk est le Ne fils de son parent.

  is_alive()

    Renvoie vrai si le processus est en vie, faux sinon.

    Grossièrement, un objet processus est en vie depuis le moment où la méthode `start()` finit de s'exécuter jusqu'à ce que le processus fils se termine.

  daemon

    L'option daemon du processus, une valeur booléenne. L'option doit être réglée avant que la méthode `start()` ne soit appelée.

    La valeur initiale est héritée par le processus créateur.

    Quand un processus se ferme, il tente de terminer tous ses processus fils daemon.

    Notez qu'un processus daemon n'est pas autorisé à créer des processus fils. Sinon un processus daemon laisserait ses fils orphelins lorsqu'il se termine par la fermeture de son parent. De plus, ce ne sont pas des daemons ou services Unix, ce sont des processus normaux qui seront terminés (et non attendus) si un processus non daemon se ferme.

  En plus de l'API `threading.Thread`, les objets `Process` supportent aussi les attributs et méthodes suivants :

  pid

    Renvoie l'ID du processus. Avant que le processus ne soit lancé, la valeur est `None`.

  exitcode

    The child's exit code. This will be `None` if the process has not yet terminated.

    If the child's `run()` method returned normally, the exit code will be 0. If it terminated via `sys.exit()` with an integer argument N, the exit code will be N.

    If the child terminated due to an exception not caught within `run()`, the exit code will be 1. If it was terminated by signal N, the exit code will be the negative value -N.

  authkey

    La clé d'authentification du processus (une chaîne d'octets).

    When `multiprocessing` is initialized the main process is assigned a random string using `os.urandom()`.

    Quand un objet `Process` est créé, il hérité de la clé d'authentification de son parent, bien que cela puisse être changé à l'aide du paramètre `authkey` pour une autre chaîne d'octets.

    Voir Clés d'authentification.

  sentinel

    Un identifiant numérique de l'objet système qui devient « prêt » quand le processus se termine.

    You can use this value if you want to wait on several events at once using `multiprocessing.connection.wait()`. Otherwise calling `join()` is simpler.

    On Windows, this is an OS handle usable with the `WaitForSingleObject` and `WaitForMultipleObjects` family of API calls. On POSIX, this is a file descriptor usable with primitives from the `select` module.

    Ajouté dans la version 3.3.

  interrupt()

    Terminate the process. Works on POSIX using the `SIGINT` signal. Behavior on Windows is undefined.

    By default, this terminates the child process by raising `KeyboardInterrupt`. This behavior can be altered by setting the respective signal handler in the child process `signal.signal()` for `SIGINT`.

    Note: if the child process catches and discards `KeyboardInterrupt`, the process will not be terminated.

    Note: the default behavior will also set `exitcode` to `1` as if an uncaught exception was raised in the child process. To have a different `exitcode` you may simply catch `KeyboardInterrupt` and call `exit(your_code)`.

    Ajouté dans la version 3.14.

  terminate()

    Terminate the process. On POSIX this is done using the `SIGTERM` signal; on Windows `TerminateProcess()` is used. Note that exit handlers and finally clauses, etc., will not be executed.

    Notez que les descendants du processus ne sont pas terminés – ils deviendront simplement orphelins.

    Avertissement

    Si cette méthode est utilisée quand le processus associé utilise un tube ou une file, alors le tube ou la file sont susceptibles d'être corrompus et peuvent devenir inutilisables par les autres processus. De façon similaire, si le processus a acquis un verrou, un sémaphore ou autre, alors le terminer est susceptible de provoquer des blocages dans les autres processus.

  kill()

    Same as `terminate()` but using the `SIGKILL` signal on POSIX.

    Ajouté dans la version 3.7.

  close()

    Ferme l'objet `Process`, libérant toutes les ressources qui lui sont associées. Une `ValueError` est levée si le processus sous-jacent tourne toujours. Une fois que `close()` se termine avec succès, la plupart des autres méthodes et attributs des objets `Process` lèveront une `ValueError`.

    Ajouté dans la version 3.7.

  Notez que les méthodes `start()`, `join()`, `is_alive()`, `terminate()` et `exitcode` ne doivent être appelées que par le processus ayant créé l'objet process.

  Exemple d'utilisation de quelques méthodes de `Process` :

      >>> import multiprocessing, time, signal
      >>> mp_context = multiprocessing.get_context('spawn')
      >>> p = mp_context.Process(target=time.sleep, args=(1000,))
      >>> print(p, p.is_alive())
      <...Process ... initial> False
      >>> p.start()
      >>> print(p, p.is_alive())
      <...Process ... started> True
      >>> p.terminate()
      >>> time.sleep(0.1)
      >>> print(p, p.is_alive())
      <...Process ... stopped exitcode=-SIGTERM> False
      >>> p.exitcode == -signal.SIGTERM
      True

exception multiprocessing.ProcessError

  The base class of all `multiprocessing` exceptions.

exception multiprocessing.BufferTooShort

  Exception raised by `Connection.recv_bytes_into()` when the supplied buffer object is too small for the message read.

  Si `e` est une instance de `BufferTooShort` alors `e.args[0]` donnera un message sous forme d'une chaîne d'octets.

exception multiprocessing.AuthenticationError

  Levée quand il y a une erreur d'authentification.

exception multiprocessing.TimeoutError

  Levée par les méthodes avec temps d'exécution limité, quand ce temps expire.

### Tubes (pipes) et files (queues)

Quand plusieurs processus travaillent ensemble, il est souvent nécessaire de les faire communiquer entre eux pour éviter d'avoir à utiliser des primitives de synchronisation comme les verrous.

Pour échanger des messages vous pouvez utiliser un `Pipe()` (pour une connexion entre deux processus) ou une file (qui autorise de plusieurs producteurs et consommateurs).

Les types `Queue`, `SimpleQueue` et `JoinableQueue` sont des files FIFO multi-producteurs et multi-consommateurs modelées sur la classe `queue.Queue` de la bibliothèque standard. Elles diffèrent par l'absence dans `Queue` des méthodes `task_done()` et `join()` introduites dans la classe `queue.Queue` par Python 2.5.

Si vous utilisez `JoinableQueue` alors vous devez appeler `JoinableQueue.task_done()` pour chaque tâche retirée de la file, sans quoi le sémaphore utilisé pour compter le nombre de tâches non accomplies pourra éventuellement déborder, levant une exception.

One difference from other Python queue implementations, is that `multiprocessing` queues serializes all objects that are put into them using `pickle`. The object returned by the get method is a re-created object that does not share memory with the original object.

Notez que vous pouvez aussi créer une file partagée en utilisant un objet gestionnaire – voir Gestionnaires.

Note

`multiprocessing` uses the usual `queue.Empty` and `queue.Full` exceptions to signal a timeout. They are not available in the `multiprocessing` namespace so you need to import them from `queue`.

Note

Quand un objet est placé dans une file, l'objet est sérialisé par pickle et un fil d'exécution en arrière-plan transmettra ensuite les données sérialisées sur un tube sous-jacent. Cela a certaines conséquences qui peuvent être un peu surprenantes, mais ne devrait causer aucune difficulté pratique — si elles vous embêtent vraiment, alors vous pouvez à la place utiliser une file créée avec un manager.

1. Après avoir placé un objet dans une file vide il peut y avoir un délai infinitésimal avant que la méthode `empty()` de la file renvoie `False` et que `get_nowait()` renvoie une valeur sans lever de `queue.Empty`.

2. Si plusieurs processus placent des objets dans la file, il est possible pour les objets d'être reçus de l'autre côté dans le désordre. Cependant, les objets placés par un même processus seront toujours récupérés dans l'ordre d'insertion.

Avertissement

Si un processus est tué à l'aide de `Process.terminate()` ou `os.kill()` pendant qu'il tente d'utiliser une `Queue`, alors les données de la file peuvent être corrompues. Cela peut par la suite causer des levées d'exceptions dans les autres processus quand ils tenteront d'utiliser la file.

Avertissement

Comme mentionné plus haut, si un processus fils a placé des éléments dans la file (et qu'il n'a pas utilisé `JoinableQueue.cancel_join_thread`), alors le processus ne se terminera pas tant que les éléments placés dans le tampon n'auront pas été transmis au tube.

Cela signifie que si vous essayez d'attendre ce processus vous pouvez obtenir un interblocage, à moins que vous ne soyez sûr que tous les éléments placés dans la file ont été consommés. De même, si le processus fils n'est pas un daemon alors le processus parent pourrait bloquer à la fermeture quand il tentera d'attendre tous ses fils non daemons.

Notez que la file créée à l'aide d'un gestionnaire n'a pas ce problème. Voir Lignes directrices de programmation.

Pour un exemple d'utilisation de files pour de la communication entre les processus, voir Exemples.

multiprocessing.Pipe(duplex=True)

  Renvoie une paire `(conn1, conn2)` d'objets `Connection` représentant les extrémités d'un tube.

  Si duplex vaut `True` (par défaut), alors le tube est bidirectionnel. Si duplex vaut `False` il est unidirectionnel : `conn1` ne peut être utilisé que pour recevoir des messages et `conn2` que pour en envoyer.

  The `send()` method serializes the object using `pickle` and the `recv()` re-creates the object.

class multiprocessing.Queue([maxsize])

  Renvoie une file partagée entre les processus utilisant un tube et quelques verrous / sémaphores. Quand un processus place initialement un élément sur la file, un fil d'exécution chargeur est démarré pour transférer les objets du tampon vers le tube.

  Instantiating this class may set the global start method. See Global start method for more details.

  Les exceptions habituelles `queue.Empty` et `queue.Full` du module `queue` de la bibliothèque standard sont levées pour signaler les timeouts.

  `Queue` implements all the methods of `queue.Queue` except for `task_done()`, `join()`, and `shutdown()`.

  qsize()

    Renvoie la taille approximative de la file. Ce nombre n'est pas fiable en raison des problématiques de multithreading et multiprocessing.

    Note that this may raise `NotImplementedError` on platforms like macOS where `sem_getvalue()` is not implemented.

  empty()

    Renvoie `True` si la file est vide, `False` sinon. Cette valeur n'est pas fiable en raison des problématiques de multithreading et multiprocessing.

    May raise an `OSError` on closed queues. (not guaranteed)

  full()

    Renvoie `True` si la file est pleine, `False` sinon. Cette valeur n'est pas fiable en raison des problématiques de multithreading et multiprocessing.

  put(obj[, block[, timeout]])

    Place obj dans la file. Si l'argument optionnel block vaut `True` (par défaut) est que timeout est `None` (par défaut), bloque jusqu'à ce qu'une place libre soit disponible. Si timeout est un nombre positif, la méthode bloquera au maximum timeout secondes et lève une exception `queue.Full` si aucune place libre n'a été trouvée dans le temps imparti. Autrement (block vaut `False`), place un élément dans la file si une place libre est immédiatement disponible, ou lève une exception `queue.Full` dans le cas contraire (timeout est ignoré dans ce cas).

    Modifié dans la version 3.8: si la file a été marquée comme fermée, une `ValueError` est levée. Auparavant, une `AssertionError` était levée.

  put_nowait(obj)

    Équivalent à `put(obj, False)`.

  get([block[, timeout]])

    Retire et renvoie un élément de la file. Si l'argument optionnel block vaut `True` (par défaut) et que timeout est `None` (par défaut), bloque jusqu'à ce qu'un élément soit disponible. Si timeout (le délai maximal autorisé) est un nombre positif, la méthode bloque au maximum timeout secondes et lève une exception `queue.Empty` si aucun élément n'est disponible dans le temps imparti. Autrement (block vaut `False`), renvoie un élément s'il est immédiatement disponible, ou lève une exception `queue.Empty` dans le cas contraire (timeout est ignoré dans ce cas).

    Modifié dans la version 3.8: si la file a été marquée comme terminée, une `ValueError` est levée. Auparavant, une `OSError`. était levée.

  get_nowait()

    Équivalent à `get(False)`.

  `multiprocessing.Queue` possède quelques méthodes additionnelles non présentes dans `queue.Queue`. Ces méthodes ne sont habituellement pas nécessaires pour la plupart des codes :

  close()

    Ferme la file : libère les ressources internes.

    A queue must not be used anymore after it is closed. For example, `get()`, `put()` and `empty()` methods must no longer be called.

    The background thread will quit once it has flushed all buffered data to the pipe. This is called automatically when the queue is garbage collected.

  join_thread()

    Attend le fil d'exécution d'arrière-plan. Elle peut seulement être utilisée une fois que `close()` a été appelée. Elle bloque jusqu'à ce que le fil d'arrière-plan se termine, assurant que toutes les données du tampon ont été transmises au tube.

    Par défaut si un processus n'est pas le créateur de la file alors à la fermeture elle essaie d'attendre le fil d'exécution d'arrière-plan de la file. Le processus peut appeler `cancel_join_thread()` pour que `join_thread()` ne fasse rien.

  cancel_join_thread()

    Empêche `join_thread()` de bloquer. En particulier, cela empêche le fil d'arrière-plan d'être attendu automatiquement quand le processus se ferme – voir `join_thread()`.

    Un meilleur nom pour cette méthode pourrait être `allow_exit_without_flush()`. Cela peut provoquer des pertes de données placées dans la file, et il est très rare d'avoir besoin de l'utiliser. Elle n'est là que si vous souhaitez terminer immédiatement le processus sans transférer les données du tampon, et que vous êtes prêt à perdre des données.

  Note

  Le fonctionnement de cette classe requiert une implémentation de sémaphore partagé sur le système d'exploitation hôte. Sans cela, la fonctionnalité est désactivée et la tentative d'instancier une `Queue` lève une `ImportError`. Voir bpo-3770 pour plus d'informations. Cette remarque reste valable pour les autres types de files spécialisées définies par la suite.

class multiprocessing.SimpleQueue

  Un type de `Queue` simplifié, très proche d'un `Pipe` avec verrou.

  Instantiating this class may set the global start method. See Global start method for more details.

  close()

    Ferme la file : libère les ressources internes.

    Une file ne doit plus être utilisée après sa fermeture. Par exemple, les méthodes `get()`, `put()` et `empty()` ne doivent plus être appelées.

    Ajouté dans la version 3.9.

  empty()

    Renvoie `True` si la file est vide, `False` sinon.

    Always raises an `OSError` if the SimpleQueue is closed.

  get()

    Supprime et renvoie un élément de la file.

  put(item)

    Place item dans la file.

class multiprocessing.JoinableQueue([maxsize])

  `JoinableQueue`, une sous-classe de `Queue`, est une file qui ajoute des méthodes `task_done()` et `join()`.

  Instantiating this class may set the global start method. See Global start method for more details.

  task_done()

    Indique qu'une tâche précédemment placée dans la file est achevée. Utilisée par les consommateurs de la file. Pour chaque `get()` utilisée pour récupérer une tâche, un appel ultérieur à `task_done()` indique à la file que le traitement de la tâche est terminé.

    Si un `join()` est actuellement bloquant, il se débloquera quand tous les éléments auront été traités (signifiant qu'un appel à `task_done()` a été reçu pour chaque élément ayant été placé via `put()` dans la file).

    Lève une exception `ValueError` si appelée plus de fois qu'il y avait d'éléments dans la file.

  join()

    Bloque jusqu'à ce que tous les éléments de la file aient été récupérés et traités.

    Le compteur des tâches non accomplies augmente chaque fois qu'un élément est ajouté à la file. Le compteur redescend chaque fois qu'un consommateur appelle `task_done()` pour indiquer qu'un élément a été récupéré et que tout le travail qui le concerne est complété. Quand le compteur des tâches non accomplies atteint zéro, `join()` est débloquée.

### Divers

multiprocessing.active_children()

  Renvoie la liste de tous les fils vivants du processus courant.

  Appeler cette méthode provoque l'effet de bord d'attendre tout processus qui n'a pas encore terminé.

multiprocessing.cpu_count()

  Renvoie le nombre de CPUs sur le système.

  This number is not equivalent to the number of CPUs the current process can use. The number of usable CPUs can be obtained with `os.process_cpu_count()` (or `len(os.sched_getaffinity(0))`).

  Une `NotImplementedError` est levée quand il est impossible de déterminer ce nombre.

  Voir aussi

  `os.cpu_count()` `os.process_cpu_count()`

  Modifié dans la version 3.13: The return value can also be overridden using the `-X cpu_count` flag or `PYTHON_CPU_COUNT` as this is merely a wrapper around the `os` cpu count APIs.

multiprocessing.current_process()

  Renvoie l'objet `Process` correspondant au processus courant.

  Un analogue à `threading.current_thread()`.

multiprocessing.parent_process()

  Renvoie l'objet `Process` correspondant au processus père de `current_process()`. Pour le processus maître, `parent_process` vaut `None`.

  Ajouté dans la version 3.8.

multiprocessing.freeze_support()

  Add support for when a program which uses `multiprocessing` has been frozen to produce an executable. (Has been tested with py2exe, PyInstaller and cx_Freeze.)

  Cette fonction doit être appelée juste après la ligne `if __name__ == '__main__'` du module principal. Par exemple :

      from multiprocessing import Process, freeze_support

      def f():
          print('hello world!')

      if __name__ == '__main__':
          freeze_support()
          Process(target=f).start()

  Si la ligne `freeze_support()` est omise, alors tenter de lancer l'exécutable figé lève une `RuntimeError`.

  Calling `freeze_support()` has no effect when the start method is not spawn. In addition, if the module is being run normally by the Python interpreter (the program has not been frozen), then `freeze_support()` has no effect.

multiprocessing.get_all_start_methods()

  Returns a list of the supported start methods, the first of which is the default. The possible start methods are `'fork'`, `'spawn'` and `'forkserver'`. Not all platforms support all methods. See Contextes et méthodes de démarrage.

  Ajouté dans la version 3.4.

multiprocessing.get_context(method=None)

  Return a context object which has the same attributes as the `multiprocessing` module.

  If method is `None` then the default context is returned. Note that if the global start method has not been set, this will set it to the system default See Global start method for more details. Otherwise method should be `'fork'`, `'spawn'`, `'forkserver'`. `ValueError` is raised if the specified start method is not available. See Contextes et méthodes de démarrage.

  Ajouté dans la version 3.4.

multiprocessing.get_start_method(allow_none=False)

  Renvoie le nom de la méthode de démarrage utilisée pour démarrer le processus.

  If the global start method is not set and allow_none is `False`, the global start method is set to the default, and its name is returned. See Global start method for more details.

  The return value can be `'fork'`, `'spawn'`, `'forkserver'` or `None`. See Contextes et méthodes de démarrage.

  Ajouté dans la version 3.4.

  Modifié dans la version 3.8: sur macOS, la méthode de démarrage spawn est maintenant la méthode par défaut. La méthode de démarrage fork doit être considérée comme dangereuse car elle peut entraîner des plantages du sous-processus. Voir bpo-33725.

multiprocessing.set_executable(executable)

  Set the path of the Python interpreter to use when starting a child process. (By default `sys.executable` is used). Embedders will probably need to do something like

      set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))

  avant de pouvoir créer des processus fils.

  Modifié dans la version 3.4: Now supported on POSIX when the `'spawn'` start method is used.

  Modifié dans la version 3.11: Accepte un path-like object.

multiprocessing.set_forkserver_preload(module_names, *, on_error='ignore')

  Set a list of module names for the forkserver main process to attempt to import so that their already imported state is inherited by forked processes. This can be used as a performance enhancement to avoid repeated work in every process.

  For this to work, it must be called before the forkserver process has been launched (before creating a `Pool` or starting a `Process`).

  The on_error parameter controls how `ImportError` exceptions during module preloading are handled: `"ignore"` (default) silently ignores failures, `"warn"` causes the forkserver subprocess to emit an `ImportWarning` to stderr, and `"fail"` causes the forkserver subprocess to exit with the exception traceback on stderr, making subsequent process creation fail with `EOFError` or `ConnectionError`.

  Only meaningful when using the `'forkserver'` start method. See Contextes et méthodes de démarrage.

  Ajouté dans la version 3.4.

  Modifié dans la version 3.15: Added the on_error parameter.

multiprocessing.set_start_method(method, force=False)

  Set the method which should be used to start child processes. The method argument can be `'fork'`, `'spawn'` or `'forkserver'`. Raises `RuntimeError` if the start method has already been set and force is not `True`. If method is `None` and force is `True` then the start method is set to `None`. If method is `None` and force is `False` then the context is set to the default context.

  Notez que cette fonction ne devrait être appelée qu'une fois au plus, et l'appel devrait être protégé à l'intérieur d'une clause `if __name__ == '__main__'` dans le module principal.

  See Contextes et méthodes de démarrage.

  Ajouté dans la version 3.4.

Note

`multiprocessing` contains no analogues of `threading.active_count()`, `threading.enumerate()`, `threading.settrace()`, `threading.setprofile()`, `threading.Timer`, or `threading.local`.

### Objets de connexions

Les objets de connexion autorisent l'envoi et la réception d'objets sérialisables ou de chaînes de caractères. Ils peuvent être vus comme des interfaces de connexion (sockets) connectées orientées messages.

Les objets de connexion sont habituellement créés via `Pipe` – voir aussi Auditeurs et Clients.

class multiprocessing.connection.Connection
  send(obj)

    Envoie un objet sur l'autre extrémité de la connexion, qui devra être lu avec `recv()`.

    L'objet doit être sérialisable. Les pickles très larges (approximativement 32 Mo+, bien que cela dépende de l'OS) pourront lever une exception `ValueError`.

  recv()

    Renvoie un objet envoyé depuis l'autre extrémité de la connexion en utilisant `send()`. Bloque jusqu'à ce que quelque chose soit reçu. Lève une `EOFError` s'il n'y a plus rien à recevoir et que l'autre extrémité a été fermée.

  fileno()

    Renvoie le descripteur de fichier ou identifiant utilisé par la connexion.

  close()

    Ferme la connexion.

    Elle est appelée automatiquement quand la connexion est collectée par le ramasse-miettes.

  poll([timeout])

    Renvoie vrai ou faux selon si des données sont disponibles à la lecture.

    Si timeout n'est pas spécifié la méthode renverra immédiatement. Si timeout est un nombre alors il spécifie le temps maximum de blocage en secondes. Si timeout est `None`, un temps d'attente infini est utilisé.

    Notez que plusieurs objets de connexions peuvent être attendus en même temps à l'aide de `multiprocessing.connection.wait()`.

  send_bytes(buf[, offset[, size]])

    Envoie des données binaires depuis un bytes-like object comme un message complet.

    If offset is given then data is read from that position in buf. If size is given then that many bytes will be read from buf. Very large buffers (approximately 32 MiB+, though it depends on the OS) may raise a `ValueError` exception

  recv_bytes([maxlength])

    Renvoie un message complet de données binaires envoyées depuis l'autre extrémité de la connexion comme une chaîne de caractères. Bloque jusqu'à ce qu'il y ait quelque chose à recevoir. Lève une `EOFError` s'il ne reste rien à recevoir et que l'autre côté de la connexion a été fermé.

    Si maxlength est précisé que que le message est plus long que maxlength alors une `OSError` est levée et la connexion n'est plus lisible.

    Modifié dans la version 3.3: Cette fonction levait auparavant une `IOError`, qui est maintenant un alias pour `OSError`.

  recv_bytes_into(buf[, offset])

    Read into buf a complete message of byte data sent from the other end of the connection and return the number of bytes in the message. Blocks until there is something to receive. Raises `EOFError` if there is nothing left to receive and the other end was closed.

    buf must be a writable bytes-like object. If offset is given then the message will be written into the buffer from that position. Offset must be a non-negative integer less than the length of buf (in bytes).

    Si le tampon est trop petit une exception `BufferTooShort` est levée et le message complet est accessible via `e.args[0]` où `e` est l'instance de l'exception.

  Modifié dans la version 3.3: Les objets de connexions eux-mêmes peuvent maintenant être transférés entre les processus en utilisant `Connection.send()` et `Connection.recv()`.

  Connection objects also now support the context management protocol -- see Le type gestionnaire de contexte. `__enter__()` returns the connection object, and `__exit__()` calls `close()`.

Par exemple :

    >>> from multiprocessing import Pipe
    >>> a, b = Pipe()
    >>> a.send([1, 'hello', None])
    >>> b.recv()
    [1, 'hello', None]
    >>> b.send_bytes(b'thank you')
    >>> a.recv_bytes()
    b'thank you'
    >>> import array
    >>> arr1 = array.array('i', range(5))
    >>> arr2 = array.array('i', [0] * 10)
    >>> a.send_bytes(arr1)
    >>> count = b.recv_bytes_into(arr2)
    >>> assert count == len(arr1) * arr1.itemsize
    >>> arr2
    array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])

Avertissement

La méthode `Connection.recv()` désérialise automatiquement les données qu'elle reçoit, ce qui peut être un risque de sécurité à moins que vous ne fassiez réellement confiance au processus émetteur du message.

Par conséquent, à moins que l'objet de connexion soit instancié par `Pipe()`, vous ne devriez uniquement utiliser les méthodes `recv()` et `send()` après avoir effectué une quelconque forme d'authentification. Voir Clés d'authentification.

Avertissement

Si un processus est tué pendant qu'il essaye de lire ou écrire sur le tube, alors les données du tube ont des chances d'être corrompues, parce qu'il devient impossible d'être sûr d'où se trouvent les bornes du message.

### Primitives de synchronisation

Généralement les primitives de synchronisation ne sont pas nécessaire dans un programme multi-processus comme elles le sont dans un programme multi-fils d'exécution. Voir la documentation du module `threading`.

Notez que vous pouvez aussi créer des primitives de synchronisation en utilisant un objet gestionnaire – voir Gestionnaires.

class multiprocessing.Barrier(parties[, action[, timeout]])

  Un objet barrière : un clone de `threading.Barrier`.

  Instantiating this class may set the global start method. See Global start method for more details.

  Ajouté dans la version 3.3.

class multiprocessing.BoundedSemaphore([value])

  Un objet sémaphore lié : un analogue proche de `threading.BoundedSemaphore`.

  Instantiating this class may set the global start method. See Global start method for more details.

  Une seule différence existe avec son proche analogue : le premier argument de sa méthode `acquire` est appelé block, pour la cohérence avec `Lock.acquire()`.

  locked()

    Return a boolean indicating whether this object is locked right now.

    Ajouté dans la version 3.14.

  Note

  Sur macOS, elle n'est pas distinguable de la classe `Semaphore` parce que `sem_getvalue()` n'est pas implémentée sur cette plateforme.

class multiprocessing.Condition([lock])

  Une variable conditionnelle : un alias pour `threading.Condition`.

  If lock is specified then it should be a `Lock` or `RLock` object from `multiprocessing`.

  Instantiating this class may set the global start method. See Global start method for more details.

  Modifié dans la version 3.3: La méthode `wait_for()` a été ajoutée.

class multiprocessing.Event

  Un clone de `threading.Event`.

  Instantiating this class may set the global start method. See Global start method for more details.

class multiprocessing.Lock

  Un verrou non récursif : un analogue proche de `threading.Lock`. Une fois que le processus ou le fil d'exécution a acquis un verrou, les tentatives suivantes d'acquisition depuis n'importe quel processus ou fil d'exécution bloqueront jusqu'à ce qu'il soit libéré ; n'importe quel processus ou fil peut le libérer. Les concepts et comportements de `threading.Lock` qui s'appliquent aux fils d'exécution sont répliqués ici dans `multiprocessing.Lock` et s'appliquent aux processus et aux fils d'exécution, à l'exception de ce qui est indiqué.

  Notez que `Lock` est en fait une fonction factory qui renvoie une instance de `multiprocessing.synchronize.Lock` initialisée avec un contexte par défaut.

  Instantiating this class may set the global start method. See Global start method for more details.

  `Lock` supporte le protocole context manager et peut ainsi être utilisé avec une instruction `with`.

  acquire(block=True, timeout=None)

    Acquiert un verrou, bloquant ou non bloquant.

    Avec l'argument block à `True` (par défaut), l'appel de méthode bloquera jusqu'à ce que le verrou soit dans déverrouillé, puis le verrouillera avant de renvoyer `True`. Notez que le nom de ce premier argument diffère de celui de `threading.Lock.acquire()`.

    Avec l'argument block à `False`, l'appel de méthode ne bloque pas. Si le verrou est actuellement verrouillé, renvoie `False` ; autrement verrouille le verrou et renvoie `True`.

    Quand invoqué avec un nombre flottant positif comme timeout, bloque au maximum pendant ce nombre spécifié de secondes, tant que le verrou ne peut être acquis. Les invocations avec une valeur de timeout négatives sont équivalents à zéro. Les invocations avec un timeout à `None` (par défaut) correspondent à un délai d'attente infini. Notez que le traitement des valeurs de timeout négatives et `None` diffère du comportement implémenté dans `threading.Lock.acquire()`. L'argument timeout n'a pas d'implication pratique si l'argument block est mis ) `False` et est alors ignoré. Renvoie `True` si le verrou a été acquis et `False` si le temps de timeout a expiré.

  release()

    Libère un verrou. Elle peut être appelée depuis n'importe quel processus ou fil d'exécution, pas uniquement le processus ou le fil qui a acquis le verrou à l'origine.

    Le comportement est le même que `threading.Lock.release()` excepté que lorsque la méthode est appelée sur un verrou déverrouillé, une `ValueError` est levée.

  locked()

    Return a boolean indicating whether this object is locked right now.

    Ajouté dans la version 3.14.

class multiprocessing.RLock

  Un objet verrou récursif : un analogue proche de `threading.RLock`. Un verrou récursif doit être libéré par le processus ou le fil d'exécution qui l'a acquis. Quand un processus ou un fil acquiert un verrou récursif, le même processus/fil peut l'acquérir à nouveau sans bloquer ; le processus/fil doit le libérer autant de fois qu'il l'acquiert.

  Notez que `RLock` est en fait une fonction factory qui renvoie une instance de `multiprocessing.synchronize.RLock` initialisée avec un contexte par défaut.

  Instantiating this class may set the global start method. See Global start method for more details.

  `RLock` supporte le protocole context manager et peut ainsi être utilisée avec une instruction `with`.

  acquire(block=True, timeout=None)

    Acquiert un verrou, bloquant ou non bloquant.

    Quand invoqué avec l'argument block à `True`, bloque jusqu'à ce que le verrou soit déverrouillé (n'appartenant à aucun processus ou fil d'exécution) sauf s'il appartient déjà au processus ou fil d'exécution courant. Le processus ou fil d'exécution courant prend la possession du verrou (s'il ne l'a pas déjà) et incrémente d'un le niveau de récursion du verrou, renvoyant ainsi `True`. Notez qu'il y a plusieurs différences dans le comportement de ce premier argument comparé à l'implémentation de `threading.RLock.acquire()`, à commencer par le nom de l'argument lui-même.

    Quand invoqué avec l'argument block à `False`, ne bloque pas. Si le verrou est déjà acquis (et possédé) par un autre processus ou fil d'exécution, le processus/fil courant n'en prend pas la possession et le niveau de récursion n'est pas incrémenté, résultant en une valeur de retour à `False`. Si le verrou est déverrouillé, le processus/fil courant en prend possession et incrémente son niveau de récursion, renvoyant `True`.

    L'usage et les comportements de l'argument timeout sont les mêmes que pour `Lock.acquire()`. Notez que certains de ces comportements diffèrent par rapport à ceux implémentés par `threading.RLock.acquire()`.

  release()

    Libère un verrou, décrémentant son niveau de récursion. Si après la décrémentation le niveau de récursion est zéro, réinitialise le verrou à un état déverrouillé (n'appartenant à aucun processus ou fil d'exécution) et si des processus/fils attendent que le verrou se déverrouillé, autorise un seul d'entre-eux à continuer. Si après cette décrémentation le niveau de récursion est toujours strictement positif, le verrou reste verrouillé et propriété du processus/fil appelant.

    N'appelez cette méthode que si le processus ou fil d'exécution appelant est propriétaire du verrou. Une `AssertionError` est levée si cette méthode est appelée par un processus/fil autre que le propriétaire ou si le verrou n'est pas verrouillé (possédé). Notez que le type d'exception levé dans cette situation diffère du comportement de `threading.RLock.release()`.

  locked()

    Return a boolean indicating whether this object is locked right now.

    Ajouté dans la version 3.14.

class multiprocessing.Semaphore([value])

  Un objet sémaphore, proche analogue de `threading.Semaphore`.

  Instantiating this class may set the global start method. See Global start method for more details.

  Une seule différence existe avec son proche analogue : le premier argument de sa méthode `acquire` est appelé block, pour la cohérence avec `Lock.acquire()`.

  get_value()

    Return the current value of semaphore.

    Note that this may raise `NotImplementedError` on platforms like macOS where `sem_getvalue()` is not implemented.

  locked()

    Return a boolean indicating whether this object is locked right now.

    Ajouté dans la version 3.14.

Note

Sous macOS, `sem_timedwait` n'est pas pris en charge, donc appeler `acquire()` avec un temps d'exécution limité émule le comportement de cette fonction en utilisant une boucle d'attente.

Note

Certaines des fonctionnalités de ce paquet requièrent une implémentation fonctionnelle de sémaphores partagés sur le système hôte. Sans cela, le module `multiprocessing.synchronize` sera désactivé, et les tentatives de l'importer lèveront une `ImportError`. Voir bpo-3770 pour plus d'informations.

### Objets `ctypes` partagés

Il est possible de créer des objets partagés utilisant une mémoire partagée pouvant être héritée par les processus fils.

multiprocessing.Value(typecode_or_type, *args, lock=True)

  Renvoie un objet `ctypes` alloué depuis la mémoire partagée. Par défaut la valeur de retour est en fait un wrapper synchronisé autour de l'objet. L'objet en lui-même est accessible par l'attribut value de l'une `Value`.

  typecode_or_type détermine le type de l'objet renvoyé : il s'agit soit d'un type ctype soit d'un caractère typecode tel qu'utilisé par le module `array`. *args est passé au constructeur de ce type.

  Si lock vaut `True` (par défaut), alors un nouveau verrou récursif est créé pour synchroniser l'accès à la valeur. Si lock est un objet `Lock` ou `RLock` alors il sera utilisé pour synchroniser l'accès à la valeur. Si lock vaut `False`, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « process-safe ».

  Les opérations telles que `+=` qui impliquent une lecture et une écriture ne sont pas atomiques. Ainsi si vous souhaitez par exemple réaliser une incrémentation atomique sur une valeur partagée, vous ne pouvez pas simplement faire

      counter.value += 1

  En supposant que le verrou associé est récursif (ce qui est le cas par défaut), vous pouvez à la place faire

      with counter.get_lock():
          counter.value += 1

  Notez que lock est un argument keyword-only.

multiprocessing.Array(typecode_or_type, size_or_initializer, *, lock=True)

  Renvoie un tableau ctypes alloué depuis la mémoire partagée. Par défaut la valeur de retour est en fait un wrapper synchronisé autour du tableau.

  typecode_or_type determines the type of the elements of the returned array: it is either a ctypes type or a one character typecode of the kind used by the `array` module with the exception of `'w'`, which is not supported. In addition, the `'c'` typecode is an alias for `ctypes.c_char`. If size_or_initializer is an integer, then it determines the length of the array, and the array will be initially zeroed. Otherwise, size_or_initializer is a sequence which is used to initialize the array and whose length determines the length of the array.

  Si lock vaut `True` (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si lock est un objet `Lock` ou `RLock` alors il sera utilisé pour synchroniser l'accès à la valeur. Si lock vaut `False`, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « process-safe ».

  Notez que lock est un argument keyword-only.

  Note that an array of `ctypes.c_char` has value and raw attributes which can both be used to store and retrieve byte strings. While raw allows interaction with a `bytes` object the full size of the array, reading value will terminate after a null byte, like most programming languages handle strings.

#### The `multiprocessing.sharedctypes` module

The `multiprocessing.sharedctypes` module provides functions for allocating `ctypes` objects from shared memory which can be inherited by child processes.

Note

Bien qu'il soit possible de stocker un pointeur en mémoire partagée, rappelez-vous qu'un pointer référence un emplacement dans l'espace d'adressage d'un processus particulier. Ainsi, ce pointeur a de fortes chances d'être invalide dans le contexte d'un autre processus et déréférencer le pointeur depuis ce second processus peut causer un plantage.

multiprocessing.sharedctypes.RawArray(typecode_or_type, size_or_initializer)

  Renvoie un tableau ctypes alloué depuis la mémoire partagée.

  typecode_or_type détermine le type des éléments du tableau renvoyé : il s'agit soit d'un type ctype soit d'un caractère codant le type des éléments du tableau (typecode) tel qu'utilisé par le module `array`. Si size_or_initialize est un entier, alors il détermine la taille du tableau, et le tableau sera initialisé avec des zéros. Autrement, size_or_initializer est une séquence qui sera utilisée pour initialiser le tableau et dont la taille détermine celle du tableau.

  Notez que définir ou récupérer un élément est potentiellement non atomique – utilisez plutôt `Array()` pour vous assurer de synchroniser automatiquement avec un verrou.

multiprocessing.sharedctypes.RawValue(typecode_or_type, *args)

  Renvoie un objet ctypes alloué depuis la mémoire partagée.

  typecode_or_type détermine le type de l'objet renvoyé : il s'agit soit d'un type ctype soit d'un caractère typecode tel qu'utilisé par le module `array`. *args est passé au constructeur de ce type.

  Notez que définir ou récupérer un élément est potentiellement non atomique – utilisez plutôt `Value()` pour vous assurer de synchroniser automatiquement avec un verrou.

  Notez qu'un tableau de `ctypes.c_char` a ses attributs value et raw qui permettent de l'utiliser pour stocker et récupérer des chaînes de caractères – voir la documentation de `ctypes`.

multiprocessing.sharedctypes.Array(typecode_or_type, size_or_initializer, *, lock=True, ctx=None)

  Identique à `RawArray()` à l'exception que suivant la valeur de lock un wrapper de synchronisation process-safe pourra être renvoyé à la place d'un tableau ctypes brut.

  Si lock vaut `True` (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si lock est un objet `Lock` ou `RLock` alors il sera utilisé pour synchroniser l'accès à la valeur. Si lock vaut `False`, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « process-safe ».

  ctx is a context object, or `None` (use the current context). If `None`, calling this may set the global start method. See Global start method for more details.

  Note that lock and ctx are keyword-only parameters.

multiprocessing.sharedctypes.Value(typecode_or_type, *args, lock=True, ctx=None)

  Identique à `RawValue()` à l'exception que suivant la valeur de lock un wrapper de synchronisation process-safe pourra être renvoyé à la place d'un objet ctypes brut.

  Si lock vaut `True` (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si lock est un objet `Lock` ou `RLock` alors il sera utilisé pour synchroniser l'accès à la valeur. Si lock vaut `False`, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « process-safe ».

  ctx is a context object, or `None` (use the current context). If `None`, calling this may set the global start method. See Global start method for more details.

  Note that lock and ctx are keyword-only parameters.

multiprocessing.sharedctypes.copy(obj)

  Renvoie un objet ctypes alloué depuis la mémoire partagée, qui est une copie de l'objet ctypes obj.

multiprocessing.sharedctypes.synchronized(obj, lock=None, ctx=None)

  Renvoie un wrapper process-safe autour de l'objet ctypes qui utilise lock pour synchroniser l'accès. Si lock est `None` (par défaut), un objet `multiprocessing.RLock` est créé automatiquement.

  ctx is a context object, or `None` (use the current context). If `None`, calling this may set the global start method. See Global start method for more details.

  Un wrapper synchronisé aura deux méthodes en plus de celles de l'objet qu'il enveloppe : `get_obj()` renvoie l'objet wrappé et `get_lock()` renvoie le verrou utilisé pour la synchronisation.

  Notez qu'accéder à l'objet ctypes à travers le wrapper peut s'avérer beaucoup plus lent qu'accéder directement à l'objet ctypes brut.

  Modifié dans la version 3.5: Les objets synchronisés supportent le protocole context manager.

Le tableau ci-dessous compare la syntaxe de création des objets ctypes partagés depuis une mémoire partagée avec la syntaxe normale ctypes. (Dans le tableau, `MyStruct` est une sous-classe quelconque de `ctypes.Structure`.)

ctypes | sharedctypes utilisant un type | sharedctypes utilisant un typecode
--- | --- | ---
c_double(2.4) | RawValue(c_double, 2.4) | RawValue('d', 2.4)
MyStruct(4, 6) | RawValue(MyStruct, 4, 6) |
(c_short * 7)() | RawArray(c_short, 7) | RawArray('h', 7)
(c_int * 3)(9, 2, 8) | RawArray(c_int, (9, 2, 8)) | RawArray('i', (9, 2, 8))

Ci-dessous un exemple où des objets ctypes sont modifiés par un processus fils :

    from multiprocessing import Process, Lock
    from multiprocessing.sharedctypes import Value, Array
    from ctypes import Structure, c_double

    class Point(Structure):
        _fields_ = [('x', c_double), ('y', c_double)]

    def modify(n, x, s, A):
        n.value **= 2
        x.value **= 2
        s.value = s.value.upper()
        for a in A:
            a.x **= 2
            a.y **= 2

    if __name__ == '__main__':
        lock = Lock()

        n = Value('i', 7)
        x = Value(c_double, 1.0/3.0, lock=False)
        s = Array('c', b'hello world', lock=lock)
        A = Array(Point, [(1.875,-6.25), (-5.75,2.0), (2.375,9.5)], lock=lock)

        p = Process(target=modify, args=(n, x, s, A))
        p.start()
        p.join()

        print(n.value)
        print(x.value)
        print(s.value)
        print([(a.x, a.y) for a in A])

Les résultats affichés sont

    49
    0.1111111111111111
    HELLO WORLD
    [(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]

### Gestionnaires

Les gestionnaires fournissent un moyen de créer des données qui peuvent être partagées entre les différents processus, incluant le partage à travers le réseau entre des processus tournant sur des machines différentes. Un objet gestionnaire contrôle un processus serveur qui gère les shared objects. Les autres processus peuvent accéder aux objets partagés à l'aide de mandataires.

multiprocessing.Manager()

  Renvoie un objet `SyncManager` démarré qui peut être utilisé pour partager des objets entre les processus. L'objet gestionnaire renvoyé correspond à un processus fils instancié et possède des méthodes pour créer des objets partagés et renvoyer les mandataires correspondants.

Les processus gestionnaires seront arrêtés dès qu'ils seront collectés par le ramasse-miettes ou que leur processus parent se terminera. Les classes gestionnaires sont définies dans le module `multiprocessing.managers` :

class multiprocessing.managers.BaseManager(address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)

  Crée un objet BaseManager.

  Une fois créé il faut appeler `start()` ou `get_server().serve_forever()` pour assurer que l'objet gestionnaire référence un processus gestionnaire démarré.

  address est l'adresse sur laquelle le processus gestionnaire écoute pour de nouvelles connexions. Si address est `None`, une adresse arbitraire est choisie.

  authkey est la clé d'authentification qui sera utilisée pour vérifier la validité des connexions entrantes sur le processus serveur. Si authkey est `None` alors `current_process().authkey` est utilisée. Autrement authkey est utilisée et doit être une chaîne d'octets.

  serializer must be `'pickle'` (use `pickle` serialization) or `'xmlrpclib'` (use `xmlrpc.client` serialization).

  ctx is a context object, or `None` (use the current context). If `None`, calling this may set the global start method. See Global start method for more details.

  shutdown_timeout is a timeout in seconds used to wait until the process used by the manager completes in the `shutdown()` method. If the shutdown times out, the process is terminated. If terminating the process also times out, the process is killed.

  Modifié dans la version 3.11: Added the shutdown_timeout parameter.

  start([initializer[, initargs]])

    Démarre un sous-processus pour démarrer le gestionnaire. Si initializer n'est pas `None` alors le sous-processus appellera `initializer(*initargs)` quand il démarrera.

  get_server()

    Renvoie un objet `Server` qui représente le serveur sous le contrôle du gestionnaire. L'objet `Server` supporte la méthode `serve_forever()` :

        >>> from multiprocessing.managers import BaseManager
        >>> manager = BaseManager(address=('', 50000), authkey=b'abc')
        >>> server = manager.get_server()
        >>> server.serve_forever()

    `Server` possède en plus un attribut `address`.

  connect()

    Connecte un objet gestionnaire local au processus gestionnaire distant :

        >>> from multiprocessing.managers import BaseManager
        >>> m = BaseManager(address=('127.0.0.1', 50000), authkey=b'abc')
        >>> m.connect()

  shutdown()

    Stoppe le processus utilisé par le gestionnaire. Cela est disponible uniquement si `start()` a été utilisée pour démarrer le processus serveur.

    Cette méthode peut être appelée plusieurs fois.

  register(typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])

    Une méthode de classe qui peut être utilisée pour enregistrer un type ou un appelable avec la classe gestionnaire.

    typeif est un « type identifier » qui est utilisé pour identifier un type particulier d'objet partagé. Cela doit être une chaîne de caractères.

    callable est un objet appelable utilisé pour créer les objets avec cet identifiant de type. Si une instance de gestionnaire prévoit de se connecter au serveur en utilisant sa méthode `connect()` ou si l'argument create_method vaut `False` alors cet argument peut être laissé à `None`.

    proxytype est une sous-classe de `BaseProxy` utilisée pour créer des mandataires autour des objets partagés avec ce typeid. S'il est `None`, une classe mandataire sera créée automatiquement.

    exposed est utilisé pour préciser une séquence de noms de méthodes dont les mandataires pour ce typeid doivent être autorisés à accéder via `BaseProxy._callmethod()`. (Si exposed est `None` alors `proxytype._exposed_` est utilisé à la place s'il existe.) Dans le cas où aucune liste exposed n'est précisée, toutes les « méthodes publiques » de l'objet partagé seront accessibles. (Ici une « méthode publique » signifie n'importe quel attribut qui possède une méthode `__call__()` et dont le nom ne commence pas par un `'_'`.)

    method_to_typeid est un tableau associatif utilisé pour préciser le type de retour de ces méthodes exposées qui doivent renvoyer un mandataire. Il associé un nom de méthode à une chaîne de caractères typeid. (Si method_to_typeid est `None`, `proxytype._method_to_typeid_` est utilisé à la place s'il existe). Si le nom d'une méthode n'est pas une clé de ce tableau associatif ou si la valeur associée est `None`, l'objet renvoyé par la méthode sera une copie de la valeur.

    create_method détermine si une méthode devrait être créée avec le nom typeid, qui peut être utilisée pour indiquer au processus serveur de créer un nouvel objet partagé et d'en renvoyer un mandataire. a valeur par défaut est `True`.

  Les instances de `BaseManager` ont aussi une propriété en lecture seule :

  address

    L'adresse utilisée par le gestionnaire.

  Modifié dans la version 3.3: Les objets gestionnaires supportent le protocole des gestionnaires de contexte – voir Le type gestionnaire de contexte. `__enter__()` démarre le processus serveur (s'il n'a pas déjà été démarré) et renvoie l'objet gestionnaire. `__exit__()` appelle `shutdown()`.

  Dans les versions précédentes `__enter__()` ne démarrait pas le processus serveur du gestionnaire s'il n'était pas déjà démarré.

class multiprocessing.managers.SyncManager

  Une sous-classe de `BaseManager` qui peut être utilisée pour la synchronisation entre processus. Des objets de ce type sont renvoyés par `multiprocessing.Manager()`.

  Ces méthodes créent et renvoient des Objets mandataires pour un certain nombre de types de données communément utilisés pour être synchronisés entre les processus. Elles incluent notamment des listes et dictionnaires partagés.

  Barrier(parties[, action[, timeout]])

    Crée un objet `threading.Barrier` partagé et renvoie un mandataire pour cet objet.

    Ajouté dans la version 3.3.

  BoundedSemaphore([value])

    Crée un objet `threading.BoundedSemaphore` partagé et renvoie un mandataire pour cet objet.

  Condition([lock])

    Crée un objet `threading.Condition` partagé et renvoie un mandataire pour cet objet.

    Si lock est fourni alors il doit être un mandataire pour un objet `threading.Lock` ou `threading.RLock`.

    Modifié dans la version 3.3: La méthode `wait_for()` a été ajoutée.

  Event()

    Crée un objet `threading.Event` partagé et renvoie un mandataire pour cet objet.

  Lock()

    Crée un objet `threading.Lock` partagé et renvoie un mandataire pour cet objet.

  Namespace()

    Crée un objet `Namespace` partagé et renvoie un mandataire pour cet objet.

  Queue([maxsize])

    Crée un objet `queue.Queue` partagé et renvoie un mandataire pour cet objet.

  RLock()

    Crée un objet `threading.RLock` partagé et renvoie un mandataire pour cet objet.

  Semaphore([value])

    Crée un objet `threading.Semaphore` partagé et renvoie un mandataire pour cet objet.

  Array(typecode, sequence)

    Crée un tableau et renvoie un mandataire pour cet objet.

  Value(typecode, value)

    Crée un objet avec un attribut `value` accessible en écriture et renvoie un mandataire pour cet objet.

  dict()
  dict(mapping)
  dict(sequence)

    Crée un objet `dict` partagé et renvoie un mandataire pour cet objet.

  list()
  list(sequence)

    Crée un objet `list` partagé et renvoie un mandataire pour cet objet.

  set()
  set(sequence)
  set(mapping)

    Create a shared `set` object and return a proxy for it.

    Ajouté dans la version 3.14: `set` support was added.

  Modifié dans la version 3.6: Les objets partagés peuvent être imbriqués. Par exemple, un conteneur partagé tel qu'une liste partagée peu contenir d'autres objets partagés qui seront aussi gérés et synchronisés par le `SyncManager`.

class multiprocessing.managers.Namespace

  Un type qui peut être enregistré avec `SyncManager`.

  Un espace de nommage n'a pas de méthodes publiques, mais possède des attributs accessibles en écriture. Sa représentation montre les valeurs de ses attributs.

  Cependant, en utilisant un mandataire pour un espace de nommage, un attribut débutant par `'_'` est un attribut du mandataire et non de l'objet cible :

      >>> mp_context = multiprocessing.get_context('spawn')
      >>> manager = mp_context.Manager()
      >>> Global = manager.Namespace()
      >>> Global.x = 10
      >>> Global.y = 'hello'
      >>> Global._z = 12.3    # this is an attribute of the proxy
      >>> print(Global)
      Namespace(x=10, y='hello')

#### Gestionnaires personnalisés

Pour créer son propre gestionnaire, il faut créer une sous-classe de `BaseManager` et utiliser la méthode de classe `register()` pour enregistrer de nouveaux types ou callables au gestionnaire. Par exemple :

    from multiprocessing.managers import BaseManager

    class MathsClass:
        def add(self, x, y):
            return x + y
        def mul(self, x, y):
            return x * y

    class MyManager(BaseManager):
        pass

    MyManager.register('Maths', MathsClass)

    if __name__ == '__main__':
        with MyManager() as manager:
            maths = manager.Maths()
            print(maths.add(4, 3))         # prints 7
            print(maths.mul(7, 8))         # prints 56

#### Utiliser un gestionnaire distant

Il est possible de lancer un serveur gestionnaire sur une machine et d'avoir des clients l'utilisant sur d'autres machines (en supposant que les pare-feus impliqués l'autorisent).

Exécuter les commandes suivantes crée un serveur pour une file simple partagée à laquelle des clients distants peuvent accéder :

    >>> from multiprocessing.managers import BaseManager
    >>> from queue import Queue
    >>> queue = Queue()
    >>> class QueueManager(BaseManager): pass
    >>> QueueManager.register('get_queue', callable=lambda:queue)
    >>> m = QueueManager(address=('', 50000), authkey=b'abracadabra')
    >>> s = m.get_server()
    >>> s.serve_forever()

Un client peut accéder au serveur comme suit :

    >>> from multiprocessing.managers import BaseManager
    >>> class QueueManager(BaseManager): pass
    >>> QueueManager.register('get_queue')
    >>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
    >>> m.connect()
    >>> queue = m.get_queue()
    >>> queue.put('hello')

Un autre client peut aussi l'utiliser :

    >>> from multiprocessing.managers import BaseManager
    >>> class QueueManager(BaseManager): pass
    >>> QueueManager.register('get_queue')
    >>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
    >>> m.connect()
    >>> queue = m.get_queue()
    >>> queue.get()
    'hello'

Les processus locaux peuvent aussi accéder à cette file, utilisant le code précédent sur le client pour y accéder à distance :

    >>> from multiprocessing import Process, Queue
    >>> from multiprocessing.managers import BaseManager
    >>> class Worker(Process):
    ...     def __init__(self, q):
    ...         self.q = q
    ...         super().__init__()
    ...     def run(self):
    ...         self.q.put('local hello')
    ...
    >>> queue = Queue()
    >>> w = Worker(queue)
    >>> w.start()
    >>> class QueueManager(BaseManager): pass
    ...
    >>> QueueManager.register('get_queue', callable=lambda: queue)
    >>> m = QueueManager(address=('', 50000), authkey=b'abracadabra')
    >>> s = m.get_server()
    >>> s.serve_forever()

### Objets mandataires

Un mandataire est un objet qui référence un objet partagé appartenant (supposément) à un processus différent. L'objet partagé est appelé le référent du mandataire. Plusieurs mandataires peuvent avoir un même référent.

Un mandataire possède des méthodes qui appellent les méthodes correspondantes du référent (bien que toutes les méthodes du référent ne soient pas nécessairement accessibles à travers le mandataire). De cette manière, un mandataire peut être utilisé comme le serait sont référent :

    >>> mp_context = multiprocessing.get_context('spawn')
    >>> manager = mp_context.Manager()
    >>> l = manager.list([i*i for i in range(10)])
    >>> print(l)
    [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
    >>> print(repr(l))
    <ListProxy object, typeid 'list' at 0x...>
    >>> l[4]
    16
    >>> l[2:5]
    [4, 9, 16]

Notez qu'appliquer `str()` à un mandataire renvoie la représentation du référent, alors que `repr()` renvoie celle du mandataire.

Une fonctionnalité importantes des objets mandataires est qu'ils sont sérialisables et peuvent donc être échangés entre les processus. Ainsi, un référent peut contenir des Objets mandataires. Cela permet d'imbriquer des listes et dictionnaires gérés ainsi que d'autres Objets mandataires :

    >>> a = manager.list()
    >>> b = manager.list()
    >>> a.append(b)         # referent of a now contains referent of b
    >>> print(a, b)
    [<ListProxy object, typeid 'list' at ...>] []
    >>> b.append('hello')
    >>> print(a[0], b)
    ['hello'] ['hello']

De même, les mandataires de listes et dictionnaires peuvent être imbriqués dans d'autres :

    >>> l_outer = manager.list([ manager.dict() for i in range(2) ])
    >>> d_first_inner = l_outer[0]
    >>> d_first_inner['a'] = 1
    >>> d_first_inner['b'] = 2
    >>> l_outer[1]['c'] = 3
    >>> l_outer[1]['z'] = 26
    >>> print(l_outer[0])
    {'a': 1, 'b': 2}
    >>> print(l_outer[1])
    {'c': 3, 'z': 26}

Si des objets standards (non proxyfiés) `list` ou `dict` sont contenus dans un référent, les modifications sur ces valeurs mutables ne seront pas propagées à travers le gestionnaire parce que le mandataire n'a aucun moyen de savoir quand les valeurs contenues sont modifiées. Cependant, stocker une valeur dans un conteneur mandataire (qui déclenche un appel à `__setitem__` sur le mandataire) propage bien la modification à travers le gestionnaire et modifie effectivement l'élément, il est ainsi possible de réassigner la valeur modifiée au conteneur mandataire :

    # create a list proxy and append a mutable object (a dictionary)
    lproxy = manager.list()
    lproxy.append({})
    # now mutate the dictionary
    d = lproxy[0]
    d['a'] = 1
    d['b'] = 2
    # at this point, the changes to d are not yet synced, but by
    # updating the dictionary, the proxy is notified of the change
    lproxy[0] = d

Cette approche est peut-être moins pratique que d'utiliser des Objets mandataires imbriqués pour la majorité des cas d'utilisation, mais démontre aussi un certain niveau de contrôle sur la synchronisation.

Note

The proxy types in `multiprocessing` do nothing to support comparisons by value. So, for instance, we have:

    >>> manager.list([1,2,3]) == [1,2,3]
    False

Il faut à la place simplement utiliser une copie du référent pour faire les comparaisons.

class multiprocessing.managers.BaseProxy

  Les objets mandataires sont des instances de sous-classes de `BaseProxy`.

  _callmethod(methodname[, args[, kwds]])

    Appelle et renvoie le résultat d'une méthode du référent du mandataire.

    Si `proxy` est un mandataire sont le référent est `obj`, alors l'expression

        proxy._callmethod(methodname, args, kwds)

    s'évalue comme

        getattr(obj, methodname)(*args, **kwds)

    dans le processus du gestionnaire.

    La valeur renvoyée sera une copie du résultat de l'appel ou un mandataire sur un nouvel objet partagé – voir l'a documentation de l'argument method_to_typeid de `BaseManager.register()`.

    Si une exception est levée par l'appel, elle est relayée par `_callmethod()`. Si une autre exception est levée par le processus du gestionnaire, elle est convertie en une `RemoteError` et est levée par `_callmethod()`.

    Notez en particulier qu'une exception est levée si methodname n'est pas exposée.

    Un exemple d'utilisation de `_callmethod()` :

        >>> l = manager.list(range(10))
        >>> l._callmethod('__len__')
        10
        >>> l._callmethod('__getitem__', (slice(2, 7),)) # equivalent to l[2:7]
        [2, 3, 4, 5, 6]
        >>> l._callmethod('__getitem__', (20,))          # equivalent to l[20]
        Traceback (most recent call last):
        ...
        IndexError: list index out of range

  _getvalue()

    Renvoie une copie du référent.

    Si le référent n'est pas sérialisable, une exception est levée.

  __repr__()

    Renvoie la représentation de l'objet mandataire.

  __str__()

    Renvoie la représentation du référent.

#### Nettoyage

Un mandataire utilise un callback sous une référence faible de façon à ce que quand il est collecté par le ramasse-miettes, il se désenregistre auprès du gestionnaire qui possède le référent.

Un objet partagé est supprimé par le processus gestionnaire quand plus aucun mandataire ne le référence.

### Pools de processus

On peut créer un pool de processus qui exécuteront les tâches qui lui seront soumises avec la classe `Pool`.

class multiprocessing.pool.Pool([processes[, initializer[, initargs[, maxtasksperchild[, context]]]]])

  Un objet process pool qui contrôle un pool de processus workers auquel sont soumises des tâches. Il supporte les résultats asynchrones avec des timeouts et des callbacks et possède une implémentation parallèle de map.

  processes is the number of worker processes to use. If processes is `None` then the number returned by `os.process_cpu_count()` is used.

  Si initializer n'est pas `None`, chaque processus worker appellera `initializer(*initargs)` en démarrant.

  maxtasksperchild est le nombre de tâches qu'un processus worker peut accomplir avant de se fermer et d'être remplacé par un worker frais, pour permettre aux ressources inutilisées d'être libérées. Par défaut maxtasksperchild est `None`, ce qui signifie que le worker vit aussi longtemps que le pool.

  context can be used to specify the context used for starting the worker processes. Usually a pool is created using the function `multiprocessing.Pool()` or the `Pool()` method of a context object. In both cases context is set appropriately. If `None`, calling this function will have the side effect of setting the current global start method if it has not been set already. See the `get_context()` function.

  Notez que les méthodes de l'objet pool ne doivent être appelées que par le processus qui l'a créé.

  Avertissement

  Les objets `multiprocessing.pool` ont des ressources internes qui doivent être correctement gérées (comme toute autre ressource) en utilisant le pool comme gestionnaire de contexte ou en appelant `close()` et `terminate()` manuellement. Si cela n'est pas fait, le processus peut être bloqué à la finalisation.

  Notez qu'il n'est pas correct de compter sur le ramasse-miette pour détruire le pool car CPython ne garantit pas que le finalizer du pool est appelé (voir `object.__del__()` pour plus d'informations).

  Modifié dans la version 3.2: Added the maxtasksperchild parameter.

  Modifié dans la version 3.4: Added the context parameter.

  Modifié dans la version 3.13: processes uses `os.process_cpu_count()` by default, instead of `os.cpu_count()`.

  Note

  Worker processes within a `Pool` typically live for the complete duration of the Pool's work queue. A frequent pattern found in other systems (such as Apache, mod_wsgi, etc) to free resources held by workers is to allow a worker within a pool to complete only a set amount of work before exiting, being cleaned up and a new process spawned to replace the old one. The maxtasksperchild argument to the `Pool` exposes this ability to the end user.

  apply(func[, args[, kwds]])

    Appelle func avec les arguments args et les arguments nommés kwds. Bloque jusqu'à ce que que le résultat soit prêt. En raison de ce blocage, `apply_async()` est préférable pour exécuter du travail en parallèle. De plus, func est exécutée sur un seul des workers du pool.

  apply_async(func[, args[, kwds[, callback[, error_callback]]]])

    Une variante de la méthode `apply()` qui renvoie un objet `AsyncResult`.

    Si callback est précisé alors ce doit être un objet appelable qui accepte un seul argument. Quand le résultat est prêt, callback est appelé avec ce résultat, si l'appel n'échoue pas auquel cas error_callback est appelé à la place.

    Si error_callback est précisé alors ce doit être un objet appelable qui accepte un seul argument. Si la fonction cible échoue, alors error_callback est appelé avec l'instance de l'exception.

    Les callbacks doivent se terminer immédiatement, autrement le fil d'exécution qui gère les résultats se retrouverait bloqué.

  map(func, iterable[, chunksize])

    Un équivalent parallèle de la fonction native `map()` (qui ne prend qu'un seul argument itérable ; pour en passer plusieurs, référez-vous à `starmap()`). Elle bloque jusqu'à ce que le résultat soit prêt.

    La méthode découpe l'itérable en un nombre de morceaux qu'elle envoie au pool de processus comme des tâches séparées. La taille (approximative) de ces morceaux peut être précisée en passant à chunksize un entier positif.

    Notez que cela peut entraîner une grosse consommation de mémoire pour les itérables très longs. Envisagez d'utiliser `imap()` ou `imap_unordered()` avec l'option chunksize explicite pour une meilleure efficacité.

  map_async(func, iterable[, chunksize[, callback[, error_callback]]])

    Une variante de la méthode `map()` qui renvoie un objet `AsyncResult`.

    Si callback est précisé alors ce doit être un objet appelable qui accepte un seul argument. Quand le résultat est prêt, callback est appelé avec ce résultat, si l'appel n'échoue pas auquel cas error_callback est appelé à la place.

    Si error_callback est précisé alors ce doit être un objet appelable qui accepte un seul argument. Si la fonction cible échoue, alors error_callback est appelé avec l'instance de l'exception.

    Les callbacks doivent se terminer immédiatement, autrement le fil d'exécution qui gère les résultats se retrouverait bloqué.

  imap(func, iterable[, chunksize])

    Une version paresseuse de `map()`.

    L'argument chunksize est le même que celui utilisé par la méthode `map()`. Pour de très longs itérables, utiliser une grande valeur pour chunksize peut faire s'exécuter la tâche beaucoup plus rapidement qu'en utilisant la valeur par défaut de `1`.

    Aussi, si chucksize vaut `1` alors la méthode `next()` de l'itérateur renvoyé par `imap()` prend un paramètre optionnel timeout : `next(timeout)` lève une `multiprocessing.TimeoutError` si le résultat ne peut pas être renvoyé avant timeout secondes.

  imap_unordered(func, iterable[, chunksize])

    Identique à `imap()` si ce n'est que l'ordre des résultats de l'itérateur renvoyé doit être considéré comme arbitraire. (L'ordre n'est garanti que quand il n'y a qu'un worker.)

  starmap(func, iterable[, chunksize])

    Like `map()` except that the elements of the iterable are expected to be iterables that are unpacked as arguments.

    Par conséquent un iterable `[(1,2), (3, 4)]` donnera pour résultat `[func(1,2), func(3,4)]`.

    Ajouté dans la version 3.3.

  starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])

    Une combinaison de `starmap()` et `map_async()` qui itère sur iterable (composé d'itérables) et appelle func pour chaque itérable dépaqueté. Renvoie l'objet résultat.

    Ajouté dans la version 3.3.

  close()

    Empêche de nouvelles tâches d'être envoyées à la pool. Les processus workers se terminent une fois que toutes les tâches ont été complétées.

  terminate()

    Stoppe immédiatement les processus workers sans finaliser les travaux courants. Quand l'objet pool est collecté par le ramasse-miettes, sa méthode `terminate()` est appelée immédiatement.

  join()

    Attend que les processus workers se terminent. Il est nécessaire d'appeler `close()` ou `terminate()` avant d'utiliser `join()`.

  Modifié dans la version 3.3: Les pools de workers supportent maintenant le protocole des gestionnaires de contexte – voir Le type gestionnaire de contexte. `__enter__()` renvoie l'objet pool et `__exit__()` appelle `terminate()`.

class multiprocessing.pool.AsyncResult

  La classe des résultats renvoyés par `Pool.apply_async()` et `Pool.map_async()`.

  get([timeout])

    Renvoie le résultat quand il arrive. Si timeout n'est pas `None` et que le résultat n'arrive pas avant timeout secondes, une `multiprocessing.TimeoutError` est levée. Si l'appel distance lève une exception, alors elle est relayée par `get()`.

  wait([timeout])

    Attend que le résultat soit disponible ou que timeout secondes s'écoulent.

  ready()

    Renvoie `True` ou `False` suivant si la tâche est accomplie.

  successful()

    Renvoie `True` ou `False` suivant si la tâche est accomplie sans lever d'exception. Lève une `ValueError` si le résultat n'est pas prêt.

    Modifié dans la version 3.7: Si le résultat n'est pas prêt, une `ValueError` est levée au lieu d'une `AssertionError` auparavant.

Les exemples suivants présentent l'utilisation d'un pool de workers :

    from multiprocessing import Pool
    import time

    def f(x):
        return x*x

    if __name__ == '__main__':
        with Pool(processes=4) as pool:         # start 4 worker processes
            result = pool.apply_async(f, (10,)) # evaluate "f(10)" asynchronously in a single process
            print(result.get(timeout=1))        # prints "100" unless your computer is *very* slow

            print(pool.map(f, range(10)))       # prints "[0, 1, 4,..., 81]"

            it = pool.imap(f, range(10))
            print(next(it))                     # prints "0"
            print(next(it))                     # prints "1"
            print(it.next(timeout=1))           # prints "4" unless your computer is *very* slow

            result = pool.apply_async(time.sleep, (10,))
            print(result.get(timeout=1))        # raises multiprocessing.TimeoutError

### Auditeurs et Clients

Habituellement l'échange de messages entre processus est réalisé en utilisant des files ou des objets `Connection` renvoyés par `Pipe()`.

However, the `multiprocessing.connection` module allows some extra flexibility. It basically gives a high level message oriented API for dealing with sockets or Windows named pipes. It also has support for digest authentication using the `hmac` module, and for polling multiple connections at the same time.

multiprocessing.connection.deliver_challenge(connection, authkey)

  Envoie un message généré aléatoirement à l'autre extrémité de la connexion et attend une réponse.

  Si la réponse correspond au condensat du message avec la clé authkey, alors un message de bienvenue est envoyé à l'autre extrémité de la connexion. Autrement, une `AuthenticationError` est levée.

multiprocessing.connection.answer_challenge(connection, authkey)

  Reçoit un message, calcule le condensat du message en utilisant la clé authkey, et envoie le condensat en réponse.

  Si un message de bienvenue n'est pas reçu, une `AuthenticationError` est levée.

multiprocessing.connection.Client(address[, family[, authkey]])

  Essaie d'établir une connexion avec l'auditeur qui utilise l'adresse address, renvoie une `Connection`.

  Le type de la connexion est déterminé par l'argument family, mais il peut généralement être omis puisqu'il peut être inféré depuis le format d'address. (Voir Formats d'adresses)

  If authkey is given and not `None`, it should be a byte string and will be used as the secret key for an HMAC-based authentication challenge. No authentication is done if authkey is `None`. `AuthenticationError` is raised if authentication fails. See Clés d'authentification.

class multiprocessing.connection.Listener([address[, family[, backlog[, authkey]]]])

  Une enveloppe autour d'un connecteur lié ou un tube nommé sous Windows qui écoute pour des connexions.

  address est l'adresse à utiliser par le connecteur lié ou le tube nommé de l'objet auditeur.

  Note

  Si une adresse '0.0.0.0' est utilisée, l'adresse ne sera pas un point d'accès connectable sous Windows. Si vous avez besoin d'un point d'accès connectable, utilisez '127.0.0.1'.

  family est le type de connecteur (ou tube nommé) à utiliser. Cela peut être l'une des chaînes `'AF_INET'` (pour un connecteur TCP), `'AF_UNIX'` (pour un connecteur Unix) ou `'AF_PIPE'` (pour un tube nommé sous Windows). Seulement le premier d'entre eux est garanti d'être disponible. Si family est `None`, la famille est inférée depuis le format d'address. Si address est aussi `None`, la famille par défaut est utilisée. La famille par défaut est supposée être la plus rapide disponible. Voir Formats d'adresses. Notez que si la family est `'AF_UNIX'` et qu'address est `None`, le connecteur est créé dans un répertoire temporaire privé créé avec `tempfile.mkstemp()`.

  Si l'objet auditeur utilise un connecteur alors backlog (1 par défaut) est passé à la méthode `listen()` du connecteur une fois qu'il a été lié.

  If authkey is given and not `None`, it should be a byte string and will be used as the secret key for an HMAC-based authentication challenge. No authentication is done if authkey is `None`. `AuthenticationError` is raised if authentication fails. See Clés d'authentification.

  accept()

    Accepte une connexion sur le connecteur lié ou le tube nommé de l'objet auditeur et renvoie un objet `Connection`. Si la tentative d'authentification échoue, une `AuthenticationError` est levée.

  close()

    Ferme le connecteur lié ou le tube nommé de l'objet auditeur. La méthode est appelée automatiquement quand l'auditeur est collecté par le ramasse-miettes. Il est cependant conseillé de l'appeler explicitement.

  Les objets auditeurs ont aussi les propriétés en lecture seule suivantes :

  address

    L'adresse utilisée par l'objet auditeur.

  last_accepted

    L'adresse depuis laquelle a été établie la dernière connexion. `None` si aucune n'est disponible.

  Modifié dans la version 3.3: Les objets auditeurs supportent maintenant le protocole des gestionnaires de contexte – voir Le type gestionnaire de contexte. `__enter__()` renvoie l'objet auditeur, et `__exit__()` appelle `close()`.

multiprocessing.connection.wait(object_list, timeout=None)

  Attend qu'un objet d'object_list soit prêt. Renvoie la liste de ces objets d'object_list qui sont prêts. Si timeout est un nombre flottant, l'appel bloquera au maximum ce nombre de secondes. Si timeout est `None`, l'appelle bloquera pour une durée non limitée. Un timeout négatif est équivalent à un timeout nul.

  For both POSIX and Windows, an object can appear in object_list if it is

  - un objet `Connection` accessible en lecture ;

  - un objet `socket.socket` connecté et accessible en lecture ; ou

  - l'attribut `sentinel` d'un objet `Process`.

  Une connexion (socket en anglais) est prête quand il y a des données disponibles en lecture dessus, ou que l'autre extrémité a été fermée.

  POSIX: `wait(object_list, timeout)` almost equivalent `select.select(object_list, [], [], timeout)`. The difference is that, if `select.select()` is interrupted by a signal, it can raise `OSError` with an error number of `EINTR`, whereas `wait()` will not.

  Windows: An item in object_list must either be an integer handle which is waitable (according to the definition used by the documentation of the Win32 function `WaitForMultipleObjects()`) or it can be an object with a `fileno()` method which returns a socket handle or pipe handle. (Note that pipe handles and socket handles are not waitable handles.)

  Ajouté dans la version 3.3.

Exemples

Le code serveur suivant crée un auditeur qui utilise `'secret password'` comme clé d'authentification. Il attend ensuite une connexion et envoie les données au client :

    from multiprocessing.connection import Listener
    from array import array

    address = ('localhost', 6000)     # family is deduced to be 'AF_INET'

    with Listener(address, authkey=b'secret password') as listener:
        with listener.accept() as conn:
            print('connection accepted from', listener.last_accepted)

            conn.send([2.25, None, 'junk', float])

            conn.send_bytes(b'hello')

            conn.send_bytes(array('i', [42, 1729]))

Le code suivant se connecte au serveur et en reçoit des données :

    from multiprocessing.connection import Client
    from array import array

    address = ('localhost', 6000)

    with Client(address, authkey=b'secret password') as conn:
        print(conn.recv())                  # => [2.25, None, 'junk', float]

        print(conn.recv_bytes())            # => 'hello'

        arr = array('i', [0, 0, 0, 0, 0])
        print(conn.recv_bytes_into(arr))    # => 8
        print(arr)                          # => array('i', [42, 1729, 0, 0, 0])

Le code suivant utilise `wait()` pour attendre des messages depuis plusieurs processus à la fois :

    from multiprocessing import Process, Pipe, current_process
    from multiprocessing.connection import wait

    def foo(w):
        for i in range(10):
            w.send((i, current_process().name))
        w.close()

    if __name__ == '__main__':
        readers = []

        for i in range(4):
            r, w = Pipe(duplex=False)
            readers.append(r)
            p = Process(target=foo, args=(w,))
            p.start()
            # We close the writable end of the pipe now to be sure that
            # p is the only process which owns a handle for it.  This
            # ensures that when p closes its handle for the writable end,
            # wait() will promptly report the readable end as being ready.
            w.close()

        while readers:
            for r in wait(readers):
                try:
                    msg = r.recv()
                except EOFError:
                    readers.remove(r)
                else:
                    print(msg)

#### Formats d'adresses

- une adresse `'AF_INET'` est une paire de la forme `(hostname, port)` où hostname est une chaîne et port un entier ;

- une adresse `'AF_UNIX'` est une chaîne représentant un nom de fichier sur le système de fichiers ;

- An `'AF_PIPE'` address is a string of the form `r'\\.\pipe\PipeName'`. To use `Client()` to connect to a named pipe on a remote computer called ServerName one should use an address of the form `r'\\ServerName\pipe\PipeName'` instead.

Notez que toute chaîne commençant par deux antislashs est considérée par défaut comme l'adresse d'un `'AF_PIPE'` plutôt qu'une adresse `'AF_UNIX'`.

### Clés d'authentification

Quand `Connection.recv` est utilisée, les données reçues sont automatiquement désérialisées par pickle. Malheureusement désérialiser des données depuis une source non sûre constitue un risque de sécurité. Par conséquent `Listener` et `Client()` utilisent le module `hmac` pour fournir une authentification par condensat.

Une clé d'authentification est une chaîne d'octets qui peut être vue comme un mot de passe : quand une connexion est établie, les deux interlocuteurs vont demander à l'autre une preuve qu'il connaît la clé d'authentification. (Démontrer que les deux utilisent la même clé n'implique pas d'échanger la clé sur la connexion.)

Si l'authentification est requise et qu'aucune clé n'est spécifiée alors la valeur de retour de `current_process().authkey` est utilisée (voir `Process`). Celle valeur est automatiquement héritée par tout objet `Process` créé par le processus courant. Cela signifie que (par défaut) tous les processus d'un programme multi-processus partageront une clé d'authentification unique qui peut être utilisée pour mettre en place des connexions entre-eux.

Des clés d'authentification adaptées peuvent aussi être générées par `os.urandom()`.

This authentication protects `Listener` and `Client()` connections, which are reachable by address. It is not applied to the anonymous pipes created by `Pipe()` or used internally by `Queue`. `multiprocessing` treats all local processes running as the same user as trusted; on most operating systems such processes can access each other's pipe file descriptors regardless. Applications that require isolation between processes of the same user must arrange it at the operating-system level -- for example, by running workers under a different user account or in a sandbox.

### Journalisation

Un certain support de la journalisation est disponible. Notez cependant que le le paquet `logging` n'utilise pas de verrous partagés entre les processus et il est donc possible (dépendant du type de gestionnaire) que les messages de différents processus soient mélangés.

multiprocessing.get_logger()

  Returns the logger used by `multiprocessing`. If necessary, a new one will be created.

  When first created the logger has level `logging.NOTSET` and no default handler. Messages sent to this logger will not by default propagate to the root logger.

  Notez que sous Windows les processus fils n'hériteront que du niveau du journaliseur du processus parent – toute autre personnalisation du journaliseur ne sera pas héritée.

multiprocessing.log_to_stderr(level=None)

  This function performs a call to `get_logger()` but in addition to returning the logger created by get_logger, it adds a handler which sends output to `sys.stderr` using format `'[%(levelname)s/%(processName)s] %(message)s'`. You can modify `levelname` of the logger by passing a `level` argument.

L'exemple ci-dessous présente une session avec la journalisation activée :

    >>> import multiprocessing, logging
    >>> logger = multiprocessing.log_to_stderr()
    >>> logger.setLevel(logging.INFO)
    >>> logger.warning('doomed')
    [WARNING/MainProcess] doomed
    >>> m = multiprocessing.Manager()
    [INFO/SyncManager-...] child process calling self.run()
    [INFO/SyncManager-...] created temp directory /.../pymp-...
    [INFO/SyncManager-...] manager serving at '/.../listener-...'
    >>> del m
    [INFO/MainProcess] sending shutdown message to manager
    [INFO/SyncManager-...] manager exiting with exitcode 0

Pour un tableau complet des niveaux de journalisation, voir le module `logging`.

### The `multiprocessing.dummy` module

`multiprocessing.dummy` replicates the API of `multiprocessing` but is no more than a wrapper around the `threading` module.

In particular, the `Pool` function provided by `multiprocessing.dummy` returns an instance of `ThreadPool`, which is a subclass of `Pool` that supports all the same method calls but uses a pool of worker threads rather than worker processes.

class multiprocessing.pool.ThreadPool([processes[, initializer[, initargs]]])

  Un objet qui contrôle un pool de fils d'exécution auquel des tâches peuvent être envoyées. L'interface des instances de `ThreadPool` est entièrement compatible avec celle des instances de `Pool`, et leur ressources doivent être aussi correctement gérées, soit en utilisant le pool avec un contexte, soit en appelant explicitement `close()` et `terminate()`.

  processes is the number of worker threads to use. If processes is `None` then the number returned by `os.process_cpu_count()` is used.

  Si initializer n'est pas `None`, chaque processus worker appellera `initializer(*initargs)` en démarrant.

  À la différence de `Pool`, maxtasksperchild et context ne peuvent pas être passés en arguments.

  Note

  La classe `ThreadPool` a la même interface que la classe `Pool`, dont l'implémentation repose sur un pool de processus, et a été introduite avant le module `concurrent.futures`. Par conséquent elle implémente des opérations qui n'ont pas vraiment de sens pour un pool implémenté avec des fils d'exécution et possède son propre type pour représenter le statut de tâches asynchrones, `AsyncResult`, qui n'est pas géré par les autres modules.

  Il est souvent plus judicieux d'utiliser `concurrent.futures.ThreadPoolExecutor` qui a une interface plus simple, qui a été pensée dès l'origine pour les fils d'exécution et qui renvoie des instances de `concurrent.futures.Future` qui sont compatibles avec de nombreux modules, dont `asyncio`.

## Lignes directrices de programmation

There are certain guidelines and idioms which should be adhered to when using `multiprocessing`.

### Toutes les méthodes de démarrage

Les règles suivantes s'appliquent aux méthodes de démarrage.

Éviter les états partagés

> Autant que possible, il faut éviter de transférer de gros volumes de données entre les processus.

> Il est souvent plus judicieux de se borner à utiliser des files et des tubes pour gérer la communication entre processus plutôt que d'utiliser des primitives de synchronisation plus bas-niveau.

Sérialisation

> Assurez-vous que les arguments passés aux méthodes des mandataires soient sérialisables (pickables).

Sûreté des mandataires à travers les fils d'exécution

> N'utilisez pas d'objet mandataire depuis plus d'un fil d'exécution à moins que vous ne le protégiez avec un verrou.

> Il n'y a jamais de problème à avoir plusieurs processus qui utilisent un même mandataire.

Attendre les processus zombies

> On POSIX when a process finishes but has not been joined it becomes a zombie. There should never be very many because each time a new process starts (or `active_children()` is called) all completed processes which have not yet been joined will be joined. Also calling a finished process's `Process.is_alive` will join the process. Even so it is probably good practice to explicitly join all the processes that you start.

Mieux vaut hériter que sérialiser - désérialiser

> When using the spawn or forkserver start methods many types from `multiprocessing` need to be picklable so that child processes can use them. However, one should generally avoid sending shared objects to other processes using pipes or queues. Instead you should arrange the program so that a process which needs access to a shared resource created elsewhere can inherit it from an ancestor process.

Éviter de terminer les processus

> Utiliser la méthode `Process.terminate` pour stopper un processus risque de casser ou de rendre indisponible aux autres processus des ressources partagées (comme des verrous, sémaphores, tubes et files) actuellement utilisées par le processus.

> Il est donc préférable de n'utiliser `Process.terminate` que sur les processus qui n'utilisent jamais de ressources partagées.

Attendre les processus qui utilisent des files

> Gardez à l'esprit qu'un processus qui a placé des éléments dans une file attend que tous les éléments mis en tampon soient consommés par le fil d'exécution « chargeur » du tube sous-jacent avant de se terminer (le processus fils peut appeler la méthode `Queue.cancel_join_thread` de la queue pour éviter ce comportement).

> Cela signifie que chaque fois que vous utilisez une file, vous devez vous assurer que tous les éléments qui y ont été placés ont été effectivement supprimés avant que le processus ne soit attendu. Autrement vous ne pouvez pas être sûr que les processus qui ont placé des éléments dans la file se termineront. Souvenez-vous aussi que tous les processus non daemons sont attendus automatiquement.

> L'exemple suivant provoque un interblocage :

>     from multiprocessing import Process, Queue

>     def f(q):
>         q.put('X' * 1000000)

>     if __name__ == '__main__':
>         queue = Queue()
>         p = Process(target=f, args=(queue,))
>         p.start()
>         p.join()                    # this deadlocks
>         obj = queue.get()

> Une solution ici consiste à intervertir les deux dernières lignes (ou simplement à supprimer la ligne `p.join()`).

Passer explicitement les ressources aux processus fils

> On POSIX using the fork start method, a child process can make use of a shared resource created in a parent process using a global resource. However, it is better to pass the object as an argument to the constructor for the child process.

> En plus de rendre le code (potentiellement) compatible avec Windows et les autres méthodes de démarrage, cela assure aussi que tant que le processus fils est en vie, l'objet ne sera pas collecté par le ramasse-miettes du processus parent. Cela peut être important si certaines ressources sont libérées quand l'objet est collecté par le ramasse-miettes du processus parent.

> Donc par exemple

>     from multiprocessing import Process, Lock

>     def f():
>         ... do something using "lock" ...

>     if __name__ == '__main__':
>         lock = Lock()
>         for i in range(10):
>             Process(target=f).start()

> devrait être réécrit comme

>     from multiprocessing import Process, Lock

>     def f(l):
>         ... do something using "l" ...

>     if __name__ == '__main__':
>         lock = Lock()
>         for i in range(10):
>             Process(target=f, args=(lock,)).start()

Faire attention à remplacer `sys.stdin` par un objet simili-fichier

> `multiprocessing` originally unconditionally called:

>     os.close(sys.stdin.fileno())

> dans la méthode `multiprocessing.Process._bootstrap()` — cela provoquait des problèmes avec les processus imbriqués. Cela peut être changé en :

>     sys.stdin.close()
>     sys.stdin = open(os.open(os.devnull, os.O_RDONLY), closefd=False)

> Which solves the fundamental issue of processes colliding with each other resulting in a bad file descriptor error, but introduces a potential danger to applications which replace `sys.stdin()` with a "file-like object" with output buffering. This danger is that if multiple processes call `close()` on this file-like object, it could result in the same data being flushed to the object multiple times, resulting in corruption.

> Si vous écrivez un objet simili-fichier et implémentez votre propre cache, vous pouvez le rendre sûr pour les forks en stockant le pid chaque fois que vous ajoutez des données au cache, et annulez le cache quand le pid change. Par exemple :

>     @property
>     def cache(self):
>         pid = os.getpid()
>         if pid != self._pid:
>             self._pid = pid
>             self._cache = []
>         return self._cache

> Pour plus d'informations, voir bpo-5155, bpo-5313 et bpo-5331

### Les méthodes de démarrage spawn et forkserver

There are a few extra restrictions which don't apply to the fork start method.

Contraintes supplémentaires sur la sérialisation

> Ensure that all arguments to `Process` are picklable. Also, if you subclass `Process.__init__`, you must make sure that instances will be picklable when the `Process.start` method is called.

Variables globales

> Gardez en tête que si le code exécuté dans un processus fils essaie d'accéder à une variable globale, alors la valeur qu'il voit (s'il y en a une) pourrait ne pas être la même que la valeur du processus parent au moment même où `Process.start` est appelée.

> Cependant, les variables globales qui sont juste des constantes de modules ne posent pas de problèmes.

Importation sécurisée du module principal

> Make sure that the main module can be safely imported by a new Python interpreter without causing unintended side effects (such as starting a new process).

> Par exemple, utiliser la méthode de démarrage spawn ou forkserver pour lancer le module suivant échouerait avec une `RuntimeError` :

>     from multiprocessing import Process

>     def foo():
>         print('hello')

>     p = Process(target=foo)
>     p.start()

> Vous devriez plutôt protéger le « point d'entrée » du programme en utilisant `if __name__ == '__main__':` comme suit :

>     from multiprocessing import Process, freeze_support, set_start_method

>     def foo():
>         print('hello')

>     if __name__ == '__main__':
>         freeze_support()
>         set_start_method('spawn')
>         p = Process(target=foo)
>         p.start()

> (La ligne `freeze_support()` peut être omise si le programme est uniquement lancé normalement et pas figé.)

> Cela permet aux interpréteurs Python fraîchement instanciés d'importer en toute sécurité le module et d'exécution ensuite la fonction `foo()`.

> Des restrictions similaires s'appliquent si un pool ou un gestionnaire est créé dans le module principal.

## Exemples

Démonstration de comment créer et utiliser des gestionnaires et mandataires personnalisés :

    from multiprocessing import freeze_support
    from multiprocessing.managers import BaseManager, BaseProxy
    import operator

    ##

    class Foo:
        def f(self):
            print('you called Foo.f()')
        def g(self):
            print('you called Foo.g()')
        def _h(self):
            print('you called Foo._h()')

    # A simple generator function
    def baz():
        for i in range(10):
            yield i*i

    # Proxy type for generator objects
    class GeneratorProxy(BaseProxy):
        _exposed_ = ['__next__']
        def __iter__(self):
            return self
        def __next__(self):
            return self._callmethod('__next__')

    # Function to return the operator module
    def get_operator_module():
        return operator

    ##

    class MyManager(BaseManager):
        pass

    # register the Foo class; make `f()` and `g()` accessible via proxy
    MyManager.register('Foo1', Foo)

    # register the Foo class; make `g()` and `_h()` accessible via proxy
    MyManager.register('Foo2', Foo, exposed=('g', '_h'))

    # register the generator function baz; use `GeneratorProxy` to make proxies
    MyManager.register('baz', baz, proxytype=GeneratorProxy)

    # register get_operator_module(); make public functions accessible via proxy
    MyManager.register('operator', get_operator_module)

    ##

    def test():
        manager = MyManager()
        manager.start()

        print('-' * 20)

        f1 = manager.Foo1()
        f1.f()
        f1.g()
        assert not hasattr(f1, '_h')
        assert sorted(f1._exposed_) == sorted(['f', 'g'])

        print('-' * 20)

        f2 = manager.Foo2()
        f2.g()
        f2._h()
        assert not hasattr(f2, 'f')
        assert sorted(f2._exposed_) == sorted(['g', '_h'])

        print('-' * 20)

        it = manager.baz()
        for i in it:
            print('<%d>' % i, end=' ')
        print()

        print('-' * 20)

        op = manager.operator()
        print('op.add(23, 45) =', op.add(23, 45))
        print('op.pow(2, 94) =', op.pow(2, 94))
        print('op._exposed_ =', op._exposed_)

    ##

    if __name__ == '__main__':
        freeze_support()
        test()

En utilisant `Pool` :

    import multiprocessing
    import time
    import random
    import sys

    #
    # Functions used by test code
    #

    def calculate(func, args):
        result = func(*args)
        return '%s says that %s%s = %s' % (
            multiprocessing.current_process().name,
            func.__name__, args, result
            )

    def calculatestar(args):
        return calculate(*args)

    def mul(a, b):
        time.sleep(0.5 * random.random())
        return a * b

    def plus(a, b):
        time.sleep(0.5 * random.random())
        return a + b

    def f(x):
        return 1.0 / (x - 5.0)

    def pow3(x):
        return x ** 3

    def noop(x):
        pass

    #
    # Test code
    #

    def test():
        PROCESSES = 4
        print('Creating pool with %d processes\n' % PROCESSES)

        with multiprocessing.Pool(PROCESSES) as pool:
            #
            # Tests
            #

            TASKS = [(mul, (i, 7)) for i in range(10)] + \
                    [(plus, (i, 8)) for i in range(10)]

            results = [pool.apply_async(calculate, t) for t in TASKS]
            imap_it = pool.imap(calculatestar, TASKS)
            imap_unordered_it = pool.imap_unordered(calculatestar, TASKS)

            print('Ordered results using pool.apply_async():')
            for r in results:
                print('\t', r.get())
            print()

            print('Ordered results using pool.imap():')
            for x in imap_it:
                print('\t', x)
            print()

            print('Unordered results using pool.imap_unordered():')
            for x in imap_unordered_it:
                print('\t', x)
            print()

            print('Ordered results using pool.map() --- will block till complete:')
            for x in pool.map(calculatestar, TASKS):
                print('\t', x)
            print()

            #
            # Test error handling
            #

            print('Testing error handling:')

            try:
                print(pool.apply(f, (5,)))
            except ZeroDivisionError:
                print('\tGot ZeroDivisionError as expected from pool.apply()')
            else:
                raise AssertionError('expected ZeroDivisionError')

            try:
                print(pool.map(f, list(range(10))))
            except ZeroDivisionError:
                print('\tGot ZeroDivisionError as expected from pool.map()')
            else:
                raise AssertionError('expected ZeroDivisionError')

            try:
                print(list(pool.imap(f, list(range(10)))))
            except ZeroDivisionError:
                print('\tGot ZeroDivisionError as expected from list(pool.imap())')
            else:
                raise AssertionError('expected ZeroDivisionError')

            it = pool.imap(f, list(range(10)))
            for i in range(10):
                try:
                    x = next(it)
                except ZeroDivisionError:
                    if i == 5:
                        pass
                except StopIteration:
                    break
                else:
                    if i == 5:
                        raise AssertionError('expected ZeroDivisionError')

            assert i == 9
            print('\tGot ZeroDivisionError as expected from IMapIterator.next()')
            print()

            #
            # Testing timeouts
            #

            print('Testing ApplyResult.get() with timeout:', end=' ')
            res = pool.apply_async(calculate, TASKS[0])
            while 1:
                sys.stdout.flush()
                try:
                    sys.stdout.write('\n\t%s' % res.get(0.02))
                    break
                except multiprocessing.TimeoutError:
                    sys.stdout.write('.')
            print()
            print()

            print('Testing IMapIterator.next() with timeout:', end=' ')
            it = pool.imap(calculatestar, TASKS)
            while 1:
                sys.stdout.flush()
                try:
                    sys.stdout.write('\n\t%s' % it.next(0.02))
                except StopIteration:
                    break
                except multiprocessing.TimeoutError:
                    sys.stdout.write('.')
            print()
            print()

    if __name__ == '__main__':
        multiprocessing.freeze_support()
        test()

Un exemple montrant comment utiliser des files pour alimenter en tâches une collection de processus workers et collecter les résultats :

    import time
    import random

    from multiprocessing import Process, Queue, current_process, freeze_support

    #
    # Function run by worker processes
    #

    def worker(input, output):
        for func, args in iter(input.get, 'STOP'):
            result = calculate(func, args)
            output.put(result)

    #
    # Function used to calculate result
    #

    def calculate(func, args):
        result = func(*args)
        return '%s says that %s%s = %s' % \
            (current_process().name, func.__name__, args, result)

    #
    # Functions referenced by tasks
    #

    def mul(a, b):
        time.sleep(0.5*random.random())
        return a * b

    def plus(a, b):
        time.sleep(0.5*random.random())
        return a + b

    #
    #
    #

    def test():
        NUMBER_OF_PROCESSES = 4
        TASKS1 = [(mul, (i, 7)) for i in range(20)]
        TASKS2 = [(plus, (i, 8)) for i in range(10)]

        # Create queues
        task_queue = Queue()
        done_queue = Queue()

        # Submit tasks
        for task in TASKS1:
            task_queue.put(task)

        # Start worker processes
        for i in range(NUMBER_OF_PROCESSES):
            Process(target=worker, args=(task_queue, done_queue)).start()

        # Get and print results
        print('Unordered results:')
        for i in range(len(TASKS1)):
            print('\t', done_queue.get())

        # Add more tasks using `put()`
        for task in TASKS2:
            task_queue.put(task)

        # Get and print some more results
        for i in range(len(TASKS2)):
            print('\t', done_queue.get())

        # Tell child processes to stop
        for i in range(NUMBER_OF_PROCESSES):
            task_queue.put('STOP')

    if __name__ == '__main__':
        freeze_support()
        test()