Provided by: manpages-fr-extra_20080618_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 *oldstate);

       int pthread_setcanceltype(int type, int *oldtype);

       void pthread_testcancel(void);

DESCRIPTION

       L’annulation est le mécanisme par lequel  un  thread  peut  interrompre
       l’exécution d’un autre thread. 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  une requête d’annulation, il se
       comporte comme si la fonction pthread_exit(PTHREAD_CANCELED) avait  été
       appelée  à  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. Consultez pthread_exit(3) pour
       plus d’informations.

       pthread_cancel() envoie une requête d’annulation au thread indiqué  par
       le paramètre thread.

       pthread_setcancelstate()   modifie   l’état   d’annulation   du  thread
       appelant, indiquant si les requêtes d’annulation sont ignorées ou  non.
       Le   paramètre   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 oldstate est différent de NULL,  le  précédent
       état  d’annulation  est sauvegardé à l’emplacement pointé par oldstate,
       et  peut  donc  être  restauré  plus  tard  par  un   autre   appel   à
       pthread_setcancelstate.

       pthread_setcanceltype()  modifie  le  mode  de  réponse  de  la requête
       d’annulation du thread appelant : asynchrone (immédiate)  ou  retardée.
       Le   paramètre   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 oldtype n’est pas égal à
       NULL,  alors  le  précédent  état   d’annulation   est   sauvegardé   à
       l’emplacement  pointé par oldtype, et peut donc être restauré plus tard
       par un autre 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 des 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 le code d’erreur suivant :

              ESRCH  Aucun  thread  correspondant au descripteur thread n’a pu
                     être trouvé.

       pthread_setcancelstate() renvoie le code d’erreur suivant :

              EINVAL Le paramètre  state  n’est  ni  PTHREAD_CANCEL_ENABLE  ni
                     PTHREAD_CANCEL_DISABLE.

       pthread_setcanceltype() renvoie le code d’erreur suivant :

              EINVAL Le  paramètre  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  bloquant  comme read(2), write(2), wait(2),
       etc.)  et les fonctions des  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 ; c’est pourquoi aucune fonction de la glibc
       n’est un point d’annulation.

       Pour les appels système, il existe 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
       qui  renvoient alors immédiatement l’erreur EINTR. Ainsi, pour vérifier
       qu’un thread n’a pas été annulé au cours de l’appel système read(), par
       exemple, on peut utiliser la méthode suivante :

              pthread_testcancel();
              retcode = read(fd, buffer, length);
              pthread_testcancel();

TRADUCTION

       Cette  page  de  manuel a été traduite par Thierry Vignaud <tvignaud AT
       mandriva DOT com> en 2000 et  révisée  par  Alain  Portal  <aportal  AT
       univ-montp2  DOT  fr>  en  2006.   La  version présente dans Debian est
       maintenue par les membres de la liste <debian-l10n-french AT lists  DOT
       debian  DOT  org>.  Veuillez signaler toute erreur de traduction par un
       rapport de bogue sur le paquet manpages-fr-extra.

                                 LinuxThreads                PTHREAD_CANCEL(3)