added wxSemaphore (with docs), new version of wxCondition and bug fixes to wxThread (patch 538242 by K.S. Sreeram)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@14907 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -505,6 +505,7 @@ capabilities of the various platforms.
 \twocolitem{\helpref{wxCriticalSection}{wxcriticalsection}}{Critical section class}
 \twocolitem{\helpref{wxCriticalSectionLocker}{wxcriticalsectionlocker}}{Critical section locker utility class}
 \twocolitem{\helpref{wxCondition}{wxcondition}}{Condition class}
+\twocolitem{\helpref{wxSemaphore}{wxsemaphore}}{Semaphore class}
 \end{twocollist}
 
 {\large {\bf HTML classes}}

docs/latex/wx/classes.tex

@@ -270,6 +270,7 @@
 \input scrolwin.tex
 \input scrlwevt.tex
 \input scrolevt.tex
+\input semaphor.tex
 \input hprovsmp.tex
 \input sngchdlg.tex
 \input snglinst.tex

docs/latex/wx/conditn.tex

@@ -12,28 +12,22 @@ perfect because in this particular case it would be much better to just
 worker threads it already makes much more sense).
 
 Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the
-other thread calls \helpref{Wait()}{wxconditionwait} but, in marked contrast
-with the pthread conditions, this will still work as the missed signals are
-queued and \helpref{Wait()}{wxconditionwait} simply returns immediately if
-there are ny pending signals.
-
-However, the calls to \helpref{Broadcast()}{wxconditionbroadcast} are {\bf not} 
-queued and so it will only wake up the threads already waiting on the
-condition. Accordingly, you will probably want to use a mutex to ensure that
-the thread(s) you want to be waken up have indeed started to wait before
-calling \helpref{Broadcast()}{wxconditionbroadcast}.
+other thread calls \helpref{Wait()}{wxconditionwait} and, just as with the
+pthread conditions, the signal is then lost and so if you want to be sure to
+get it you must use a mutex together with the condition variable.
 
 \wxheading{Example}
 
-This example shows how a main thread may launch a worker thread and wait until
-it starts running:
+This example shows how a main thread may launch a worker thread which starts
+running and then waits until the main thread signals it to continue:
 
 \begin{verbatim}
 class MyWaitingThread : public wxThread
 {
 public:
-    MyWaitingThread(wxCondition *condition)
+    MyWaitingThread(wxMutex *mutex, wxCondition *condition)
     {
+        m_mutex = mutex;
         m_condition = condition;
 
         Create();
@@ -41,8 +35,11 @@ public:
 
     virtual ExitCode Entry()
     {
-        // let the main thread know that we started running
+        // wait for the signal from the main thread: it is absolutely necessary
+        // to look the mutex before doing it!
+        m_mutex->Lock();
         m_condition->Signal();
+        m_mutex->Unlock();
 
         ... do our job ...
 
@@ -55,15 +52,23 @@ private:
 
 int main()
 {
-    wxCondition condition;
-    MyWaitingThread *thread - new MyWaitingThread(&condition);
+    wxMutex mutex;
+    wxCondition condition(&mutex);
 
-    thread->Run();
+    for ( int i = 0; i < 10; i++ )
+    {
+        MyWaitingThread *thread = new MyWaitingThread(&mutex, &condition);
 
-    // wait until the thread really starts running
-    condition.Wait();
+        thread->Run();
+    }
 
-    ...
+    // wake up one of the threads
+    condition.Signal();
+
+    // wake up all the other ones
+    condition.Broadcast();
+
+    ... wait until they terminate or do something else ...
 
     return 0;
 }
@@ -85,37 +90,57 @@ None.
 
 \membersection{wxCondition::wxCondition}\label{wxconditionconstr}
 
-\func{}{wxCondition}{\void}
+\func{}{wxCondition}{\param{wxMutex }{*mutex}}
 
-Default constructor.
+Default and only constructor. The {\it mutex} must be non {\tt NULL}.
 
 \membersection{wxCondition::\destruct{wxCondition}}
 
 \func{}{\destruct{wxCondition}}{\void}
 
-Destroys the wxCondition object.
+Destroys the wxCondition object. The destructor is not virtual so this class
+should not be used polymorphically.
 
 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
 
 \func{void}{Broadcast}{\void}
 
-Broadcasts to all waiting objects.
+Broadcasts to all waiting threads, waking all of them up. Note that this method
+may be called whether the mutex associated with this condition is locked or
+not.
+
+\wxheading{See also}
+
+\helpref{wxCondition::Signal}{wxconditionsignal}
 
 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 
 \func{void}{Signal}{\void}
 
-Signals the object.
+Signals the object waking up at most one thread. If several threads are waiting
+on the same condition, the exact thread which is woken up is undefined. If no
+threads are waiting, the signal is lost and the condition would have to be
+signalled again to wake up any thread which may start waiting on it later.
+
+Note that this method may be called whether the mutex associated with this
+condition is locked or not.
+
+\wxheading{See also}
+
+\helpref{wxCondition::Broadcast}{wxconditionbroadcast}
 
 \membersection{wxCondition::Wait}\label{wxconditionwait}
 
 \func{void}{Wait}{\void}
 
-Waits indefinitely.
+Waits until the condition is signalled.
 
 \func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
 
-Waits until a signal is raised or the timeout has elapsed.
+Waits until the condition is signalled or the timeout has elapsed.
+
+Note that the mutex associated with this condition {\bf must} be acquired by
+the thread before calling this method.
 
 \wxheading{Parameters}
 
@@ -125,5 +150,7 @@ Waits until a signal is raised or the timeout has elapsed.
 
 \wxheading{Return value}
 
-The second form returns if the signal was raised, or FALSE if there was a timeout.
+The second form returns {\tt TRUE} if the condition has been signalled, or
+{\tt FALSE} if it returned because the timeout has elapsed.
+
 

docs/latex/wx/semaphor.tex

@@ -0,0 +1,84 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        semaphore.tex
+%% Purpose:     wxSemaphore documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     02.04.02
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2002 Vadim Zeitlin
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxSemaphore}}\label{wxsemaphore}
+
+wxSemaphore is a counter limiting the number of threads concurrently accessing
+a shared resource. This counter is always between $0$ and the maximum value
+specified during the semaphore creation. When the counter is strictly greater
+than $0$, a call to \helpref{Wait}{wxsemaphorewait} returns immediately and
+decrements the counter. As soon as it reaches $0$, any subsequent calls to
+\helpref{Wait}{wxsemaphorewait} block and only return when the semaphore
+counter becomes strictly positive again as the result of calling 
+\helpref{Post}{wxsemaphorepost} which increments the counter.
+
+In general, the semaphores are useful to restict access to a shared resource
+which can only be accessed by some fixed number of clients at once. For
+example, when modeling a hotel reservation system a semaphore with the counter
+equal to the total number of available rooms could be created. Each time a room
+is reserved, the semaphore should be acquired by calling 
+\helpref{Wait}{wxsemaphorewait} and each time a room is freed it should be
+released by calling \helpref{Post}{wxsemaphorepost}.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/thread.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxSemaphore::wxSemaphore}\label{wxsemaphorewxsemaphore}
+
+\func{}{wxSemaphore}{\param{int }{initialcount = 0}, \param{int }{maxcount = 0}}
+
+Specifying a {\it maxcount} of $0$ actually makes wxSemaphore behave as if
+there is no upper limit. If maxcount is $1$ the semaphore behaves exactly as a
+mutex.
+
+{\it initialcount} is the initial value of the semaphore which must be between
+$0$ and {\it maxcount} (if it is not set to $0$).
+
+\membersection{wxSemaphore::\destruct{wxSemaphore}}\label{wxsemaphoredtor}
+
+\func{}{\destruct{wxSemaphore}}{\void}
+
+Destructor is not virtual, don't use this class polymorphically.
+
+\membersection{wxSemaphore::Post}\label{wxsemaphorepost}
+
+\func{void}{Post}{\void}
+
+Increments the semaphore count and signals one of the waiting threads in an
+atomic way.
+
+\membersection{wxSemaphore::TryWait}\label{wxsemaphoretrywait}
+
+\func{bool}{TryWait}{\void}
+
+Same as \helpref{Wait()}{wxsemaphorewait}, but does not block, returns
+{\tt TRUE} if the semaphore was successfully acquired and {\tt FALSE} if the
+count is zero and it couldn't be done.
+
+\membersection{wxSemaphore::Wait}\label{wxsemaphorewait}
+
+\func{void}{Wait}{\void}
+
+Wait indefinitely until the semaphore count becomes strictly positive
+and then decrement it and return.
+
+\func{bool}{Wait}{\param{unsigned long }{timeout\_millis}}
+
+Same as the version above, but with a timeout limit: returns {\tt TRUE| if the
+semaphore was acquired and {\tt FALSE} if the timeout has ellapsed
+