Provided by: manpages-fr_1.67.0-1_all bug

NOM

       pthread_cancel,      pthread_setcancelstate,     pthread_setcanceltype,
       pthread_testcancel - Annulation de thread.

SYNOPSIS

       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

       int pthread_setcancelstate(int state, int *etat_pred);

       int pthread_setcanceltype(int mode, int *ancien_mode);

       void pthread_testcancel(void);

DESCRIPTION

       L’annulation est le mécanisme par lequel  un  thread  peut  interrompre
       l’exécution  d’un  autre thread. C’est l’équivalent pour les threads de
       la fonction kill()  des  processus  classiques.  Plus  précisément,  un
       thread  peut  envoyer une requête d’annulation à un autre thread. Selon
       sa configuration, le thread visé peut soit  ignorer  la  requête,  soit
       l’honorer immédiatement, soit enfin retarder son application jusqu’à ce
       qu’un point d’annulation soit atteint.

       Quand un thread réalise  finalement  la  requête  d’annulation,  il  se
       comporte comme si pthread_exit(PTHREAD_CANCELED) avait été appelé à cet
       endroit : tous  les  gestionnaires  de  nettoyage  sont  exécutés  dans
       l’ordre   inverse   de  leur  enregistrement.  Puis  les  fonctions  de
       destruction des données spécifiques au thread sont appelées. Enfin,  le
       thread  interrompt définitivement son exécution en retournant la valeur
       PTHREAD_CANCELED.  Voir pthread_exit(3) pour plus d’information.

       pthread_cancel envoie une requête d’annulation au  thread  indiqué  par
       l’argument thread.

       pthread_setcancelstate  modifie  l’état  d’annulation  pour  le  thread
       appelant, c’est à dire si les requêtes d’annulation  sont  ignorées  ou
       non.   L’argument   state   est  le  nouvel  état  d’annulation :  soit
       PTHREAD_CANCEL_ENABLE   pour   autoriser    les    annulations,    soit
       PTHREAD_CANCEL_DISABLE  pour  les désactiver (les requêtes d’annulation
       sont alors ignorées). Si etat_pred est différent de NULL, le  précédent
       état  d’annulation est sauvegardé à l’emplacement pointé par etat_pred,
       et  peut  donc  être  restauré  plus  tard  par  un   autre   appel   à
       pthread_setcancelstate.

       pthread_setcanceltype  modifie  le  mode  de  la  réponse à une requête
       d’annulation  pour  le  thread  appelant :  asynchrone  (immédiate)  ou
       retardée.   L’argument  type  est  le  nouveau mode d’annulation : soit
       PTHREAD_CANCEL_ASYNCHRONOUS pour annuler le  thread  appelant  dès  que
       possible   après   la   réception   d’une  requête  d’annulation,  soit
       PTHREAD_CANCEL_DEFERRED pour mettre en attente la  requête  jusqu’à  ce
       qu’un  point d’annulation soit atteint. Si ancien_mode n’est pas égal à
       NULL,  alors  le  précédent  état   d’annulation   est   sauvegardé   à
       l’emplacement  pointé  par ancien_mode, et peut donc être restauré plus
       tard par un autres appel à pthread_setcanceltype.

       Les threads sont toujours créés par pthread_create(3)  avec  annulation
       activée  et  retardée. C’est à dire que l’état initial d’annulation est
       PTHREAD_CANCEL_ENABLE    et     que     le     mode     initial     est
       PTHREAD_CANCEL_DEFERRED.

       Les points d’annulation sont les points dans l’exécution d’un programme
       où l’on teste si des requêtes d’annulation ne sont pas  en  attente  de
       traitement.  Si  des  requêtes  sont  en attente, alors l’annulation du
       thread est exécutée. Les fonctions suivantes relatives aux  threads  de
       la norme POSIX sont des points d’annulation implicites :

              pthread_join(3)
              pthread_cond_wait(3)
              pthread_cond_timedwait(3)
              pthread_testcancel(3)
              sem_wait(3)
              sigwait(3)

       Toutes  les autres fonctions POSIX relatives aux threads sont garanties
       ne pas être des points d’annulation. C’est-à-dire qu’elles ne  traitent
       pas les requêtes d’annulation en attente de traitement.

       pthread_testcancel  ne  fait  rien  si  ce  n’est tester si une requête
       d’annulation est en attente de réalisation et la traiter.  Sa  fonction
       est  d’introduire  des  tests  explicites  pour vérifier ponctuellement
       qu’aucune requête d’annulation n’a été reçue lors des longues séquences
       de code sans points d’annulation.

VALEUR RENVOYÉE

       pthread_cancel,    pthread_setcancelstate    et   pthread_setcanceltype
       renvoient 0 en cas de succès  et  un  code  d’erreur  non  nul  en  cas
       d’erreur.

ERREURS

       pthread_cancel renvoie l’un des codes d’erreur suivants :

              ESRCH  aucun  thread  correspondant au descripteur thread n’a pu
                     ête trouvé.

       pthread_setcancelstate renvoie l’un des codes d’erreur suivants :

              EINVAL l’argument  state  n’est  ni   PTHREAD_CANCEL_ENABLE   ni
                     PTHREAD_CANCEL_DISABLE

       pthread_setcanceltype renvoie l’un des codes d’erreur suivants :

              EINVAL l’argument   type  n’est  ni  PTHREAD_CANCEL_DEFERRED  ni
                     PTHREAD_CANCEL_ASYNCHRONOUS

AUTEUR

       Xavier Leroy <Xavier.Leroy@inria.fr>

VOIR AUSSI

       pthread_exit(3), pthread_cleanup_push(3), pthread_cleanup_pop(3).

BOGUES

       POSIX spécifie qu’un certain nombre d’appels-système (fondamentalement,
       tous  les  appels-système  pouvant  bloquer  comme  read(2),  write(2),
       wait(2), etc.) et les fonctions  de  bibliothèques  qui  invoquent  ces
       appels-système  (par exemple, fprintf(3)) sont des points d’annulation.
       LinuxThreads n’est pas encore assez intégré à la bibliothèque  standard
       C pour implémenter cela ; et donc, aucune fonction de la GlibC n’est un
       point d’annulation.

       Pour les appels-système, au moins existe-t’il  un  moyen  détourné  d’y
       parvenir.  Les requêtes d’annulation sont transmises au thread ciblé en
       lui envoyant un signal. Ce dernier  va  interrompre  tous  les  appels-
       système  bloquants,  les faisant renvoyer immédiatement l’erreur EINTR.
       Aussi, vérifier qu’un thread n’a pas été annulé au  cours  de  l’appel-
       système read, par exemple, peut être réalisé de la manière suivante :

              pthread_testcancel();
              retcode = read(fd, tampon, longueur);
              pthread_testcancel();

TRADUCTION

       Thierry Vignaud <tvignaud@mandrakesoft.com>, 2000
       Christophe Blaess, 2003.