# `_thread` --- Low-level threading API

Ce module fournit les primitives de bas niveau pour travailler avec de multiples fils d'exécution (aussi appelés light-weight processes ou tasks) — plusieurs fils d'exécution de contrôle partagent leur espace de données global. Pour la synchronisation, de simples verrous (aussi appelés des mutexes ou des binary semaphores) sont fournis. Le module `threading` fournit une API de fils d'exécution de haut niveau, plus facile à utiliser et construite à partir de ce module.

Modifié dans la version 3.7: Ce module était optionnel, il est maintenant toujours disponible.

Ce module définit les constantes et les fonctions suivantes :

exception _thread.error

  Levée lors d'erreurs spécifiques aux fils d'exécution.

  Modifié dans la version 3.3: Ceci est à présent un synonyme de l'exception native `RuntimeError`.

_thread.LockType

  C'est le type d'objets verrous.

_thread.start_new_thread(function, args[, kwargs])

  Démarre un nouveau fils d'exécution et renvoie son identifiant. Ce fil d'exécution exécute la fonction function avec la liste d'arguments args (qui doit être un n-uplet). L'argument optionnel kwargs spécifie un dictionnaire d'arguments nommés.

  Au renvoi de la fonction, le fil d'exécution quitte silencieusement.

  Lorsque la fonction se termine avec une exception non gérée, `sys.unraisablehook()` est appelée pour gérer cette dernière. L'attribut object de l'argument hook est function. Par défaut, la trace d'appels est affichée puis le fil d'exécution se termine (mais les autres fils d'exécution continuent de s'exécuter).

  Lorsque la fonction lève l'exception `SystemExit`, elle est ignorée silencieusement.

  Raises an auditing event `_thread.start_new_thread` with arguments `function`, `args`, `kwargs`.

  Modifié dans la version 3.8: `sys.unraisablehook()` est maintenant utilisée pour s'occuper des exceptions non gérées.

_thread.interrupt_main(signum=signal.SIGINT, /)

  Simule l'effet d'un signal arrivant au fil d'exécution principal. Un fil d'exécution peut utiliser cette fonction pour interrompre le fil d'exécution principal, bien qu'une interruption immédiate ne soit pas garantie.

  If given, signum is the number of the signal to simulate. If signum is not given, `signal.SIGINT` is simulated.

  If the given signal isn't handled by Python (it was set to `signal.SIG_DFL` or `signal.SIG_IGN`), this function does nothing.

  Modifié dans la version 3.10: Ajout du paramètre signum pour modifier le numéro du signal.

  Note

  Cette fonction n'émet pas vraiment le signal, mais programme un appel du gestionnaire associé (à condition qu'il existe). Pour émettre réellement le signal, utilisez `signal.raise_signal()`.

_thread.exit()

  Lève une exception `SystemExit`. Quand elle n'est pas interceptée, le fil d'exécution se terminera silencieusement.

_thread.allocate_lock()

  Renvoie un nouveau verrou. Les méthodes des verrous sont décrites ci-dessous. Le verrou est initialement déverrouillé.

_thread.get_ident()

  Renvoie l'« identifiant de fil » du fil d'exécution courant. C'est un entier non nul. Sa valeur n'a pas de signification directe ; il est destiné à être utilisé comme cookie magique, par exemple pour indexer un dictionnaire de données pour chaque fil. Les identifiants de fils peuvent être recyclés lorsqu'un fil d'exécution se termine et qu'un autre fil est créé.

_thread.get_native_id()

  Renvoie l'identifiant natif complet assigné par le noyau du fil d'exécution actuel. C'est un entier non négatif. Sa valeur peut uniquement être utilisée pour identifier ce fil d'exécution à l'échelle du système (jusqu'à ce que le fil d'exécution se termine, après quoi la valeur peut être recyclée par le système d'exploitation).

  Availability: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.

  Ajouté dans la version 3.8.

  Modifié dans la version 3.13: Added support for GNU/kFreeBSD.

_thread.stack_size([size])

  Renvoie la taille de la pile d'exécution utilisée lors de la création de nouveaux fils d'exécution. L'argument optionnel size spécifie la taille de pile à utiliser pour les fils créés ultérieurement, et doit être à 0 (pour utiliser la taille de la plate-forme ou la valeur configurée par défaut) ou un entier positif supérieur ou égal à 32 768 (32 Kio). Si size n'est pas spécifié, 0 est utilisé. Si la modification de la taille de la pile de fils n'est pas prise en charge, une exception `RuntimeError` est levée. Si la taille de la pile spécifiée n'est pas valide, une exception `ValueError` est levée et la taille de la pile n'est pas modifiée. 32 Kio est actuellement la valeur minimale de taille de la pile prise en charge pour garantir un espace de pile suffisant pour l'interpréteur lui-même. Notez que certaines plates-formes peuvent avoir des restrictions particulières sur les valeurs de taille de la pile, telles que l'exigence d'une taille de pile minimale > 32 Kio ou d'une allocation en multiples de la taille de page de la mémoire du système – la documentation de la plate-forme devrait être consultée pour plus d'informations (4 Kio sont courants ; en l'absence de renseignements plus spécifiques, l'approche suggérée est l'utilisation de multiples de 4 096 octets pour la taille de la pile).

  Availability: Windows, pthreads.

  Unix platforms with POSIX threads support.

_thread.TIMEOUT_MAX

  The maximum value allowed for the timeout parameter of `Lock.acquire`. Specifying a timeout greater than this value will raise an `OverflowError`.

  Ajouté dans la version 3.2.

Les verrous ont les méthodes suivantes :

lock.acquire(blocking=True, timeout=-1)

  Sans aucun argument optionnel, cette méthode acquiert le verrou inconditionnellement, et si nécessaire attend jusqu'à ce qu'il soit relâché par un autre fil d'exécution (un seul fil d'exécution à la fois peut acquérir le verrou — c'est leur raison d'être).

  If the blocking argument is present, the action depends on its value: if it is false, the lock is only acquired if it can be acquired immediately without waiting, while if it is true, the lock is acquired unconditionally as above.

  If the floating-point timeout argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative timeout argument specifies an unbounded wait. You cannot specify a timeout if blocking is false.

  La valeur renvoyée est `True` si le verrou est acquis avec succès, sinon `False`.

  Modifié dans la version 3.2: Le paramètre timeout est nouveau.

  Modifié dans la version 3.2: Le verrou acquis peut maintenant être interrompu par des signaux sur POSIX.

lock.release()

  Relâche le verrou. Le verrou doit avoir été acquis plus tôt, mais pas nécessairement par le même fil d'exécution.

lock.locked()

  Renvoie le statut du verrou : `True` s'il a été acquis par certains fils d'exécution, sinon `False`.

En plus de ces méthodes, les objets verrous peuvent aussi être utilisés via l'instruction `with`, e.g :

    import _thread

    a_lock = _thread.allocate_lock()

    with a_lock:
        print("a_lock is locked while this executes")

Avertissements :

- Interrupts always go to the main thread (the `KeyboardInterrupt` exception will be received by that thread.)

- Appeler la fonction `sys.exit()` ou lever l'exception `SystemExit` est équivalent à appeler la fonction `_thread.exit()`.

- It is platform-dependent whether the `acquire()` method on a lock can be interrupted (so that the `KeyboardInterrupt` exception will happen immediately, rather than only after the lock has been acquired or the operation has timed out). It can be interrupted on POSIX, but not on Windows.

- Quand le fil d'exécution principal s'arrête, il est défini par le système si les autres fils d'exécution survivent. Sur beaucoup de systèmes, ils sont tués sans l'exécution des clauses `try`… `finally` ou l'exécution des destructeurs d'objets.