.\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH PTHREAD_COND 3 LinuxThreads .SH NOM pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- Opérations sur les conditions .SH SYNOPSIS \fB#include \fP \fBpthread_cond_t \fP\fIcond\fP\fB = PTHREAD_COND_INITIALIZER;\fP \fBint pthread_cond_init(pthread_cond_t *\fP\fIcond\fP\fB, pthread_condattr_t *\fP\fIcond_attr\fP\fB);\fP \fBint pthread_cond_signal(pthread_cond_t *\fP\fIcond\fP\fB);\fP \fBint pthread_cond_broadcast(pthread_cond_t *\fP\fIcond\fP\fB);\fP \fBint pthread_cond_wait(pthread_cond_t *\fP\fIcond\fP\fB, pthread_mutex_t *\fP\fImutex\fP\fB);\fP \fBint pthread_cond_timedwait(pthread_cond_t *\fP\fIcond\fP\fB, pthread_mutex_t *\fP\fImutex\fP\fB, const struct timespec *\fP\fIabstime\fP\fB);\fP \fBint pthread_cond_destroy(pthread_cond_t *\fP\fIcond\fP\fB);\fP .SH DESCRIPTION Une condition (abréviation pour «\ variable condition\ ») est un mécanisme de synchronisation permettant à un thread de suspendre son exécution jusqu'à ce qu'une certaine condition (un prédicat) sur des données partagées soit vérifiée. Les opérations fondamentales sur les conditions sont\ : signaler la condition (quand le prédicat devient vrai) et attendre la condition en suspendant l'exécution du thread jusqu'à ce qu'un autre thread signale la condition. Une variable condition doit toujours être associée à un mutex, pour éviter une condition concurrente où un thread se prépare à attendre une condition et un autre thread signale la condition juste avant que le premier n'attende réellement. \fBpthread_cond_init\fP() initialise la variable condition \fIcond\fP, en utilisant les attributs de condition spécifiés par \fIcond_attr\fP, ou les attributs par défaut si \fIcond_attr\fP vaut NULL. L'implémentation LinuxThreads ne supporte aucun attribut de condition, aussi le paramètre \fIcond_attr\fP est pour l'instant ignoré. Les variables de type \fBpthread_cond_t\fP peuvent également être statiquement initialisées, en utilisant la constante \fBPTHREAD_COND_INITIALIZER\fP. \fBpthread_cond_signal\fP() relance l'un des threads attendant la variable condition \fIcond\fP. S'il n'existe aucun thread répondant à ce critère, rien ne se produit. Si plusieurs threads attendent sur \fIcond\fP, seul l'un d'entre eux sera relancé, mais il est impossible de savoir lequel. \fBpthread_cond_broadcast\fP() relance tous les threads attendant sur la variable condition \fIcond\fP. Rien ne se passe s'il n'y a aucun thread attendant sur \fIcond\fP. \fBpthread_cond_wait\fP() déverrouille atomiquement le \fImutex\fP (comme \fBpthread_unlock_mutex\fP()) et attend que la variable condition \fIcond\fP soit signalée. L'exécution du thread est suspendue et ne consomme pas de temps CPU jusqu'à ce que la variable condition soit signalée. Le \fImutex\fP doit être verrouillé par le thread appelant à l'entrée de \fBpthread_cond_wait\fP(). Avant de rendre la main au thread appelant, \fBpthread_cond_wait\fP() reverrouille \fImutex\fP (comme \fBpthread_lock_mutex\fP()). Le déverrouillage du mutex et la suspension de l'exécution sur la variable condition sont liés atomiquement. Donc, si tous les threads verrouillent le mutex avant de signaler la condition, il est garanti que la condition ne peut être signalée (et donc ignorée) entre le moment où un thread verrouille le mutex et le moment où il attend sur la variable condition. \fBpthread_cond_timedwait\fP() déverrouille le \fImutex\fP et attend sur \fIcond\fP, en liant atomiquement ces deux étapes, comme le fait \fBpthread_cond_wait\fP(), cependant l'attente est bornée temporellement. Si \fIcond\fP n'a pas été signalée après la période spécifiée par \fIabstime\fP, le mutex \fImutex\fP est reverrouillé et \fBpthread_cond_timedwait\fP() rend la main avec l'erreur \fBETIMEDOUT\fP. Le paramètre \fIabstime\fP spécifie un temps absolu, avec la même origine que \fBtime\fP(2) et \fBgettimeofday\fP(2)\ : un \fIabstime\fP de 0 correspond à 00:00:00 GMT, le 1er Janvier 1970. \fBpthread_cond_destroy\fP() détruit une variable condition, libérant les ressources qu'elle possède. Aucun thread ne doit attendre sur la condition à l'entrée de \fBpthread_cond_destroy\fP(). Dans l'implémentation LinuxThreads, aucune ressource ne peut être associée à une variable condition, aussi \fBpthread_cond_destroy\fP() ne fait en fait rien d'autre que vérifier qu'aucun thread n'attend la condition. .SH ANNULATION \fBpthread_cond_wait\fP() et \fBpthread_cond_timedwait\fP() sont des points d'annulation. Si un thread est annulé alors qu'il est suspendu dans l'une de ces fonctions, son exécution reprend immédiatement, reverrouillant le paramètre \fImutex\fP à \fBpthread_cond_wait\fP() et \fBpthread_cond_timedwait\fP(), et exécute finalement l'annulation. Aussi, les gestionnaires d'annulation sont assurés que \fImutex\fP est verrouillé lorsqu'ils sont exécutés. .SH "ASYNC\-SIGNAL SAFETY" Ces fonctions ne sont pas fiables par rapport aux signaux asynchrones et ne doivent donc pas être utilisées dans des gestionnaires de signaux [NdT\ : sous peine de perdre leur propriété d'atomicité]. En particulier, appeler \fBpthread_cond_signal\fP() ou \fBpthread_cond_broadcast\fP() dans un gestionnaire de signal peut placer le thread appelant dans une situation de blocage définitif. .SH "VALEUR RENVOYÉE" Toutes ces fonctions renvoient 0 en cas de succès et un code d'erreur non nul en cas de problème. .SH ERREURS \fBpthread_cond_init\fP(), \fBpthread_cond_signal\fP(), \fBpthread_cond_broadcast\fP() et \fBpthread_cond_wait\fP() ne renvoient jamais de code d'erreur. La fonction \fBpthread_cond_timedwait\fP() renvoie l'un des codes d'erreur suivants en cas de problème\ : .RS .TP \fBETIMEDOUT\fP La variable condition n'a pas reçu de signal avant le délai spécifié par \fIabstime\fP. .TP \fBEINTR\fP \fBpthread_cond_timedwait\fP() a été interrompu par un signal. .RE La fonction \fBpthread_cond_destroy\fP() renvoie le code d'erreur suivant en cas de problème\ : .RS .TP \fBEBUSY\fP Il existe des threads attendant \fIcond\fP. .RE .SH AUTEUR Xavier Leroy .SH "VOIR AUSSI" \fBpthread_condattr_init\fP(3), \fBpthread_mutex_lock\fP(3), \fBpthread_mutex_unlock\fP(3), \fBgettimeofday\fP(2), \fBnanosleep\fP(2) .SH EXEMPLE Considérons deux variables globales partagées \fIx\fP et \fIy\fP, protégées par le mutex \fImut\fP, et une variable condition \fIcond\fP pour signaler que \fIx\fP devient plus grand que \fIy\fP. .RS .nf .sp \fBint x,y; pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; pthread_cond_t cond = PTHREAD_COND_INITIALIZER;\fP .LP .RE .fi Attendre que \fIx\fP devienne plus grand que \fIy\fP se réalise de la manière suivante\ : .RS .nf .sp \fBpthread_mutex_lock(&mut); while (x <= y) { pthread_cond_wait(&cond, &mut); } /* operate on x and y */ pthread_mutex_unlock(&mut);\fP .LP .RE .fi Les modifications de \fIx\fP et \fIy\fP qui peuvent rendre \fIx\fP plus grand que \fIy\fP doivent signaler la condition si nécessaire\ : .RS .nf .sp \fBpthread_mutex_lock(&mut); /* modify x and y */ if (x > y) pthread_cond_broadcast(&cond); pthread_mutex_unlock(&mut);\fP .LP .RE .fi S'il peut être prouvé qu'au plus un thread en attente nécessite d'être réveillé (par exemple, s'il n'y a que deux threads communiquant via \fIx\fP et \fIy\fP), \fBpthread_cond_signal\fP() peut être utilisé en tant qu'alternative efficace à \fBpthread_cond_broadcast\fP(). En cas de doute, utilisez \fBpthread_cond_broadcast\fP(). Pour attendre que \fIx\fP devienne plus grand que \fIy\fP avec un délai de 5 secondes, faîtes\ : .RS .nf .sp \fBstruct timeval now; struct timespec timeout; int retcode;\fP \fBpthread_mutex_lock(&mut); gettimeofday(&now); timeout.tv_sec = now.tv_sec + 5; timeout.tv_nsec = now.tv_usec * 1000; retcode = 0; while (x <= y && retcode != ETIMEDOUT) { retcode = pthread_cond_timedwait(&cond, &mut, &timeout); } if (retcode == ETIMEDOUT) { /* timeout occurred */ } else { /* operate on x and y */ } pthread_mutex_unlock(&mut);\fP .LP .RE .fi .SH TRADUCTION Cette page de manuel a été traduite par Thierry Vignaud en 2000 et révisée par Alain Portal en 2006. La version présente dans Debian est maintenue par les membres de la liste . Veuillez signaler toute erreur de traduction par un rapport de bogue sur le paquet manpages\-fr\-extra.