wxMutex Class Reference

#include <wx/thread.h>

Detailed Description

A mutex object is a synchronization object whose state is set to signaled when it is not owned by any thread, and nonsignaled when it is owned.

Its name comes from its usefulness in coordinating mutually-exclusive access to a shared resource as only one thread at a time can own a mutex object.

Mutexes may be recursive in the sense that a thread can lock a mutex which it had already locked before (instead of dead locking the entire process in this situation by starting to wait on a mutex which will never be released while the thread is waiting) but using them is not recommended under Unix and they are not recursive by default. The reason for this is that recursive mutexes are not supported by all Unix flavours and, worse, they cannot be used with wxCondition.

For example, when several threads use the data stored in the linked list, modifications to the list should only be allowed to one thread at a time because during a new node addition the list integrity is temporarily broken (this is also called program invariant).

// this variable has an "s_" prefix because it is static: seeing an "s_" in
// a multithreaded program is in general a good sign that you should use a
// mutex (or a critical section)
static wxMutex *s_mutexProtectingTheGlobalData;

// we store some numbers in this global array which is presumably used by
// several threads simultaneously
wxArrayInt s_data;

void MyThread::AddNewNode(int num)
{
    // ensure that no other thread accesses the list
    s_mutexProtectingTheGlobalList->Lock();

    s_data.Add(num);

    s_mutexProtectingTheGlobalList->Unlock();
}

// return true if the given number is greater than all array elements
bool MyThread::IsGreater(int num)
{
    // before using the list we must acquire the mutex
    wxMutexLocker lock(s_mutexProtectingTheGlobalData);

    size_t count = s_data.Count();
    for ( size_t n = 0; n < count; n++ )
    {
        if ( s_data[n] > num )
            return false;
    }

    return true;
}

Notice how wxMutexLocker was used in the second function to ensure that the mutex is unlocked in any case: whether the function returns true or false (because the destructor of the local object lock is always called). Using this class instead of directly using wxMutex is, in general, safer and is even more so if your program uses C++ exceptions.

Library:  wxBase

Category:  Threading

See Also

wxThread, wxCondition, wxMutexLocker, wxCriticalSection

Public Member Functions
	wxMutex (wxMutexType type=wxMUTEX_DEFAULT)
	Default constructor.
	~wxMutex ()
	Destroys the wxMutex object.
wxMutexError	Lock ()
	Locks the mutex object.
wxMutexError	LockTimeout (unsigned long msec)
	Try to lock the mutex object during the specified time interval.
wxMutexError	TryLock ()
	Tries to lock the mutex object.
wxMutexError	Unlock ()
	Unlocks the mutex object.

Constructor & Destructor Documentation

wxMutex::wxMutex

(

wxMutexType

type = wxMUTEX_DEFAULT

)

Default constructor.

wxMutex::~wxMutex

(

)

Destroys the wxMutex object.

Member Function Documentation

wxMutexError wxMutex::Lock

(

)

Locks the mutex object.

This is equivalent to LockTimeout() with infinite timeout.

Note that if this mutex is already locked by the caller thread, this function doesn't block but rather immediately returns.

Returns

One of: wxMUTEX_NO_ERROR, wxMUTEX_DEAD_LOCK.

wxMutexError wxMutex::LockTimeout

(

unsigned long

msec

)

Try to lock the mutex object during the specified time interval.

Returns

One of: wxMUTEX_NO_ERROR, wxMUTEX_DEAD_LOCK, wxMUTEX_TIMEOUT.

wxMutexError wxMutex::TryLock

(

)

Tries to lock the mutex object.

If it can't, returns immediately with an error.

Returns

One of: wxMUTEX_NO_ERROR, wxMUTEX_BUSY.

wxMutexError wxMutex::Unlock

(

)

Unlocks the mutex object.

Returns

One of: wxMUTEX_NO_ERROR, wxMUTEX_UNLOCKED.