pthread_setcanceltype

PTHREAD_CANCEL(3)         Manuel du programmeur Linux        PTHREAD_CANCEL(3)



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(2) 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 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 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 le code d'erreur suivant :

              ESRCH  Aucun thread correspondant au descripteur thread n'a pu
                     ête trouvé.

       pthread_setcancelstate() renvoie le code d'erreur suivant :

              EINVAL L'argument state n'est ni PTHREAD_CANCEL_ENABLE ni
                     PTHREAD_CANCEL_DISABLE.

       pthread_setcanceltype() renvoie le code d'erreur suivant :

              EINVAL L'argument type n'est ni PTHREAD_CANCEL_DEFERRED ni
                     PTHREAD_CANCEL_ASYNCHRONOUS.

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(2), par exemple, peut être réalisé de la manière
       suivante :

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

AUTEUR
       Xavier Leroy <Xavier DOT Leroy AT inria DOT fr>

VOIR AUSSI
       pthread_exit(3), pthread_cleanup_push(3), pthread_cleanup_pop(3)

TRADUCTION
       Ce document est une traduction réalisée par Thierry Vignaud <tvignaud
       AT mandriva DOT com> en 2000 et révisée le 19 novembre 2007.

       L'équipe de traduction a fait le maximum pour réaliser une adaptation
       française de qualité. La version anglaise la plus à jour de ce
       document est toujours consultable via la commande :
       « LANG=C man 3 pthread_cancel ».  N'hésitez pas à  signaler Ã
       l'auteur ou au traducteur, selon le cas, toute erreur dans cette page
       de manuel.




LinuxThreads                     11 mars 1998                PTHREAD_CANCEL(3)