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

QMutex Class

La classe QMutex permet la sérialisation des accès entre les threads. Plus d'informations...

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

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

Par exemple, supposons qu'il existe une méthode qui imprime 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, il se produit ce qui suit :

// 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 par deux threads, la séquence suivante peut 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 nous ajoutons un mutex, nous devrions obtenir le résultat que nous souhaitons :

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();
}

Un seul thread peut alors modifier number à un moment donné et le résultat est correct. Il s'agit bien sûr d'un exemple trivial, mais il s'applique à tout autre cas où les choses doivent se produire dans un ordre particulier.

Lorsque vous appelez lock() dans un thread, les autres threads qui essaient d'appeler lock() au même endroit se bloquent jusqu'à ce que le thread qui a obtenu le verrou appelle unlock(). Une alternative non bloquante à lock() est tryLock().

QMutex est optimisé pour être rapide dans le cas non prévu. Il n'allouera pas de mémoire s'il n'y a pas de contention sur ce mutex. Il est construit et détruit presque sans surcharge, ce qui signifie qu'il est possible d'avoir de nombreux mutex dans d'autres classes.

Voir aussi QRecursiveMutex, QMutexLocker, QReadWriteLock, QSemaphore, et QWaitCondition.

Documentation des fonctions membres

[constexpr noexcept] QMutex::QMutex()

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

[noexcept] QMutex::~QMutex()

Détruit le mutex.

Attention : 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 bloquera jusqu'à ce que ce thread le déverrouille.

Si le mutex a déjà été verrouillé par le thread en cours, cet appel ne renverra jamais, ce qui entraînera un blocage.

Remarque : cette fonction est noexcept lorsque FutexAlwaysAvailable est 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é avec 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 noexcept lorsque FutexAlwaysAvailable est true.

Voir aussi 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 pour que le mutex devienne disponible.

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

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

Remarque : cette fonction est noexcept lorsque FutexAlwaysAvailable est 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é avec unlock() avant qu'un autre thread puisse le verrouiller avec succès.

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 de la bibliothèque standard Lockable. 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 pour que le mutex devienne disponible.

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

Si le verrou a été obtenu, le mutex doit être déverrouillé avec 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'à timePoint pour que le mutex devienne disponible.

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

Si le verrou a été obtenu, le mutex doit être déverrouillé avec 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. La tentative de déverrouillage d'un mutex dans un thread différent de celui qui l'a verrouillé entraîne une erreur. Déverrouiller 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.