.\" This is a wxWidgets manpage page generated from the XML docs
.TH wxMutex 3wx 2005-02-15 "wxWidgets" "wxWidgets class documentation"
.SH NAME
wxMutex \- 
  Mutex class
 
.SH 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 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 thread use the data stored in the linked list,
   modifications to the list should be only 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
   
   ).
  
 
.SH "PARENTS"

.SH "INCLUDE FILES"
wx/thread.h
.SH MEMBERS

  
.SS  wxMutex (wxMutexType type = wxMUTEX_DEFAULT)

     


      Default constructor.
     
    
   
  
.SS  ~wxMutex ()

     


      Destroys the wxMutex object.
     
    
   
  
.SS wxMutexError Lock ()

     


      Locks the mutex object.
     
    
   
  
.SS wxMutexError TryLock ()

     


      Tries to lock the mutex object. If it can't, returns immediately with an
      error.
     
    
   
  
.SS wxMutexError Unlock ()

     


      Unlocks the mutex object.
     
    
 
.SH EXAMPLE

  
    // 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 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.
  
 
.SH "SEE ALSO"

  wxThread
  wxCondition
   
  wxMutexLocker
  wxCriticalSection
 
.SH "AUTHORS"
Documentation content by Julian Smart, Robert Roebling, Vadim Zeitlin, Robin Dunn, et al

Conversion to manpage format by Arnout Engelen (http://bzzt.net), bugreports welcome.