Provided by:
manpages-fr_1.67.0-1_all 
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.