"multiprocessing" --- Process-based parallelism
***********************************************

**Code source  :** Lib/multiprocessing/

======================================================================

Availability: 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"
-------------------

Dans le module "multiprocessing", les processus sont instanciés en
créant un objet "Process" et en appelant sa méthode "start()". La
classe "Process" suit la même API que "threading.Thread". Un exemple
trivial d'un programme multi-processus est

   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 unpickleable from within
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
----------------------------------

Selon la plateforme, "multiprocessing" gère trois manières de démarrer
un processus. Ces *méthodes de démarrage* sont

   *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.  Currently the default on POSIX
      except macOS.

      Note:

        The default start method will change away from *fork* in
        Python 3.14. Code that requires *fork* should 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.

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.

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" gère deux types de canaux de communication entre les
processus :

**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" contient des équivalents à toutes les primitives de
synchronisation de "threading". Par exemple il est possible d'utiliser
un verrou pour s'assurer qu'un seul processus à la fois écrit sur la
sortie standard :

   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.

Cependant, si vous devez réellement partager des données,
"multiprocessing" permet de le faire de deux manières.

**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.

   Un gestionnaire renvoyé par "Manager()" prend en charge les types
   "list", "dict", "Namespace", "Lock", "RLock", "Semaphore",
   "BoundedSemaphore", "Condition", "Event", "Barrier", "Queue",
   "Value" et "Array". Par exemple,

      from multiprocessing import Process, Manager

      def f(d, l):
          d[1] = '1'
          d['2'] = 2
          d[0.25] = None
          l.reverse()

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

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

              print(d)
              print(l)

   affiche

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

   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
=========

Le paquet "multiprocessing" reproduit en grande partie l'API du module
"threading".


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-N_1:N_2:...:N_k » est construit, où chaque N_k est le
      N^e 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).

      Quand "multiprocessing" est initialisé, une chaîne aléatoire est
      assignée au processus principal, en utilisant "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.

   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

   La classe de base de toutes les exceptions de "multiprocessing".

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 (first-in, first-out) 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 return 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" utilise les exceptions habituelles "queue.Empty"
  et "queue.Full" pour signaler un dépassement du temps maximal
  autorisé. Elles ne sont pas disponibles dans l'espace de nommage
  "multiprocessing" donc vous devez les importer depuis le module
  "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])

   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" implémente toutes les méthodes de "queue.Queue" à
   l'exception de "task_done()" et "join()".

   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)

   Renvoie un contexte ayant les mêmes attributs que le module
   "multiprocessing".

   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 some thing 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)

   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. Any "ImportError" when doing so is silently
   ignored. 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").

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

   Ajouté dans la version 3.4.

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" ne contient pas d'analogues à
  "threading.active_count()", "threading.enumerate()",
  "threading.settrace()", "threading.setprofile()", "threading.Timer",
  ou "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(buffer[, offset[, size]])

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

      Si *offset* est fourni, les données sont lues depuis cette
      position dans le tampon *buffer*. Si *size* est fourni, il
      indique le nombre d'octets qui seront lus depuis *buffer*. Les
      tampons très larges (approximativement 32 MiB+, bien que cela
      dépende de l'OS) pourront lever une exception "ValueError".

   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(buffer[, offset])

      Lit et stocke dans *buffer* un message complet de données
      binaires envoyées depuis l'autre extrémité de la connexion et
      renvoie le nombre d'octets du message. 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é.

      *buffer* doit être un *bytes-like object* accessible en
      écriture. Si *offset* est donné, le message sera écrit dans le
      tampon à partir de cette position. *offset* doit être un entier
      positif, inférieur à la taille de *buffer* (en octets).

      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()".

   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".

   Si *lock* est spécifié il doit être un objet "Lock" ou "RLock" du
   module "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.

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()".

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()".

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*.

   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.


Le module "multiprocessing.sharedctypes"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Le module "multiprocessing.sharedctypes" fournit des fonctions pour
allouer des objets "ctypes" depuis la mémoire partagée, qui peuvent
être hérités par les processus fils.

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   | *sharedctypes* utilisant un |
|                      | un type                    | *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.

   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:

  Les types de mandataires de "multiprocessing" n'implémentent rien
  pour la comparaison par valeurs. Par exemple, on a :

     >>> 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:

     Les processus *workers* à l'intérieur d'une "Pool" vivent par
     défaut aussi longtemps que la file de travail du pool. Un modèle
     fréquent chez d'autres systèmes (tels qu'Apache, *mod_wsgi*,
     etc.) pour libérer les ressources détenues par les *workers* est
     d'autoriser un *worker* dans le pool à accomplir seulement une
     certaine charge de travail avant de se fermer, se retrouvant
     nettoyé et remplacé par un nouveau processus fraîchement lancé.
     L'argument *maxtasksperchild* de "Pool" expose cette
     fonctionnalité à l'utilisateur final.

   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()".

Cependant, le module "multiprocessing.connection" permet un peu plus
de flexibilité. Il fournit un message de plus haut-niveau orienté API
pour gérer  des connecteurs ou des tubes nommés sous Windows. Il gère
aussi l'authentification par condensat (*digest authentication* en
anglais) en utilisant le module "hmac", et pour interroger de
multiples connexions en même temps.

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()".


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()

   Renvoie le journaliseur utilisé par "multiprocessing". Si
   nécessaire, un nouveau sera créé.

   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".


Le module "multiprocessing.dummy"
---------------------------------

"multiprocessing.dummy" réplique toute l'API de "multiprocessing" mais
n'est rien de plus qu'une interface autour du module "threading".

En particulier, la fonction "Pool" du module "multiprocessing.dummy"
renvoie une instance de "ThreadPool", qui est une sous-classe de
"Pool". Elle a la même interface, mais elle utilise un pool de fils
d'exécution plutôt qu'un pool de processus.

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
===================================

Il y a certaines lignes directrices et idiomes à respecter pour
utiliser "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

   Quand vous utilisez les méthodes de démarrage *spawn* ou
   *forkserver*, de nombreux types de "multiprocessing" nécessitent
   d'être sérialisés pour que les processus fils puissent les
   utiliser. Cependant, il faut généralement éviter d'envoyer des
   objets partagés aux autres processus en utilisant des tubes ou des
   files. Vous devez plutôt vous arranger pour qu'un processus qui
   nécessite l'accès à une ressource partagée créée autre part qu'il
   en hérite depuis un de ses processus ancêtres.

É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

   À l'origine, "multiprocessing" appelait inconditionnellement :

      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()
