Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QMutex Class

La classe QMutex permet de sérialiser l'accès entre les threads. En savoir plus...

En-tête : #include <QMutex>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core

Remarque : toutes les fonctions de cette classe sont sûres pour les threads.

Fonctions publiques

QMutex()
~QMutex()
void lock()
(since 6.6) bool tryLock(QDeadlineTimer timer)
bool tryLock(int timeout)
bool tryLock()
bool try_lock()
bool try_lock_for(std::chrono::duration<Rep, Period> duration)
bool try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)
void unlock()

Description détaillée

Le but d’un QMutex est de protéger un objet, une structure de données ou une section de code afin qu’un seul thread puisse y accéder à la fois (ce principe est similaire au mot-clé « synchronized » de Java). Il est généralement préférable d’utiliser un mutex avec une classe de gestion de verrouillage ( QMutexLocker ), car cela permet de s’assurer facilement que le verrouillage et le déverrouillage sont effectués de manière cohérente.

Prenons par exemple une méthode qui affiche un message à l’utilisateur sur deux lignes :

int number = 6;

void method1()
{
    number *= 5;
    number /= 4;
}

void method2()
{
    number *= 3;
    number /= 2;
}

Si ces deux méthodes sont appelées successivement, voici ce qui se passe :

// method1()
number *= 5;        // number is now 30
number /= 4;        // number is now 7

// method2()
number *= 3;        // number is now 21
number /= 2;        // number is now 10

Si ces deux méthodes sont appelées simultanément à partir de deux threads, la séquence suivante pourrait se produire :

// Thread 1 calls method1()
number *= 5;        // number is now 30

// Thread 2 calls method2().
//
// Most likely Thread 1 has been put to sleep by the operating
// system to allow Thread 2 to run.
number *= 3;        // number is now 90
number /= 2;        // number is now 45

// Thread 1 finishes executing.
number /= 4;        // number is now 11, instead of 10

Si l’on ajoute un mutex, on devrait obtenir le résultat souhaité :

QMutex mutex;
int number = 6;

void method1()
{
    mutex.lock();
    number *= 5;
    number /= 4;
    mutex.unlock();
}

void method2()
{
    mutex.lock();
    number *= 3;
    number /= 2;
    mutex.unlock();
}

Ainsi, un seul thread peut modifier ` number ` à un moment donné et le résultat est correct. Il s’agit bien sûr d’un exemple trivial, mais cela s’applique à tout autre cas où les opérations doivent se dérouler dans un ordre précis.

Lorsque vous appelez ` lock()` dans un thread, les autres threads qui tentent d’appeler ` lock()` au même endroit seront bloqués jusqu’à ce que le thread ayant obtenu le verrou appelle ` unlock()`. Une alternative non bloquante à ` lock()` est ` tryLock()`.

QMutex est optimisé pour être rapide en l’absence de contention. Il n’allouera pas de mémoire s’il n’y a pas de contention sur ce mutex. Sa construction et sa destruction ne génèrent pratiquement aucune surcharge, ce qui signifie qu’il est tout à fait possible d’avoir de nombreux mutex au sein d’autres classes.

Voir également QRecursiveMutex, QMutexLocker, QReadWriteLock, QSemaphore et QWaitCondition.

Documentation sur les fonctions membres

[constexpr noexcept default] QMutex::QMutex()

Crée un nouveau mutex. Le mutex est créé dans un état déverrouillé.

[noexcept] QMutex::~QMutex()

Détruit le mutex.

Avertissement : la destruction d'un mutex verrouillé peut entraîner un comportement indéfini.

[noexcept(...)] void QMutex::lock()

Verrouille le mutex. Si un autre thread a verrouillé le mutex, cet appel se bloquera jusqu'à ce que ce thread l'ait déverrouillé.

Si le mutex était déjà verrouillé par le thread actuel, cet appel ne reviendra jamais, ce qui provoquera un blocage réciproque.

Remarque : cette fonction est de type « noexcept » lorsque ` FutexAlwaysAvailable ` est défini comme ` true`.

Voir également ` unlock()`.

[noexcept(...), since 6.6] bool QMutex::tryLock(QDeadlineTimer timer)

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`. Si un autre thread a verrouillé le mutex, cette fonction attendra que ` timer ` expire pour que le mutex devienne disponible.

Si le verrou a été obtenu, le mutex doit être déverrouillé à l’aide de ` unlock()` avant qu’un autre thread puisse le verrouiller avec succès.

Cette fonction a été introduite dans Qt 6.6.

Remarque : cette fonction est de type « noexcept » lorsque FutexAlwaysAvailable est true.

Voir également lock() et unlock().

[noexcept(...)] bool QMutex::tryLock(int timeout)

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`. Si un autre thread a verrouillé le mutex, cette fonction attendra au maximum ` timeout ` millisecondes que le mutex se libère.

Remarque : passer un nombre négatif comme timeout revient à appeler lock(), c'est-à-dire que cette fonction attendra indéfiniment jusqu’à ce que le mutex puisse être verrouillé si timeout est négatif.

Si le verrou a été obtenu, le mutex doit être déverrouillé à l’aide de ` unlock()` avant qu’un autre thread puisse le verrouiller avec succès.

Remarque : cette fonction est de type « noexcept » lorsque FutexAlwaysAvailable est égal à true.

Voir également lock() et unlock().

[noexcept] bool QMutex::tryLock()

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`.

Si le verrou a été obtenu, le mutex doit être déverrouillé à l’aide de ` unlock()` avant qu’un autre thread puisse le verrouiller correctement.

Il s'agit d'une fonction surchargée.

Voir également lock() et unlock().

[noexcept] bool QMutex::try_lock()

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`.

Cette fonction est fournie à des fins de compatibilité avec le concept « ` Lockable` » de la bibliothèque standard. Elle est équivalente à ` tryLock()`.

template <typename Rep, typename Period> bool QMutex::try_lock_for(std::chrono::duration<Rep, Period> duration)

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`. Si un autre thread a verrouillé le mutex, cette fonction attendra au moins ` duration ` que le mutex se libère.

Remarque : passer une durée négative comme duration revient à appeler try_lock(). Ce comportement diffère de celui de tryLock().

Si le verrou a été obtenu, le mutex doit être déverrouillé à l’aide de unlock() avant qu’un autre thread puisse le verrouiller avec succès.

Voir également lock() et unlock().

template <typename Clock, typename Duration> bool QMutex::try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)

Tente de verrouiller le mutex. Cette fonction renvoie ` true ` si le verrou a été obtenu ; sinon, elle renvoie ` false`. Si un autre thread a verrouillé le mutex, cette fonction attendra au moins jusqu’à ce que ` timePoint ` pour que le mutex soit à nouveau disponible.

Remarque : passer un timePoint qui a déjà été libéré revient à appeler try_lock(). Ce comportement diffère de celui de tryLock().

Si le verrou a été obtenu, le mutex doit être déverrouillé à l’aide de unlock() avant qu’un autre thread puisse le verrouiller avec succès.

Voir également lock() et unlock().

[noexcept] void QMutex::unlock()

Déverrouille le mutex. Toute tentative de déverrouillage d’un mutex dans un thread différent de celui qui l’a verrouillé entraîne une erreur. Le déverrouillage d’un mutex qui n’est pas verrouillé entraîne un comportement indéfini.

Voir également lock().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.