src/thread/win32/win_ce_semaphore.c

   1 /* win_ce_semaphore.c
   2
   3    Copyright (c) 1998, Johnson M. Hart
   4    (with corrections 2001 by Rainer Loritz)
   5    Permission is granted for any and all use providing that this
   6    copyright is properly acknowledged.
   7    There are no assurances of suitability for any use whatsoever.
   8
   9    WINDOWS CE: There is a collection of Windows CE functions to simulate
  10    semaphores using only a mutex and an event. As Windows CE events cannot
  11    be named, these simulated semaphores cannot be named either.
  12
  13    Implementation notes:
  14    1. All required internal data structures are allocated on the process's heap.
  15    2. Where appropriate, a new error code is returned (see the header
  16       file), or, if the error is a Win32 error, that code is unchanged.
  17    3. Notice the new handle type "SYNCHHANDLE" that has handles, counters,
  18       and other information. This structure will grow as new objects are added
  19       to this set; some members are specific to only one or two of the objects.
  20    4. Mutexes are used for critical sections. These could be replaced with
  21       CRITICAL_SECTION objects but then this would give up the time out
  22       capability.
  23    5. The implementation shows several interesting aspects of synchronization, some
  24       of which are specific to Win32 and some of which are general. These are pointed
  25       out in the comments as appropriate.
  26    6. The wait function emulates WaitForSingleObject only. An emulation of
  27       WaitForMultipleObjects is much harder to implement outside the kernel,
  28       and it is not clear how to handle a mixture of WCE semaphores and normal
  29       events and mutexes. */
  30
  31 #define WIN32_LEAN_AND_MEAN
  32 #include <windows.h>
  33
  34 #include "win_ce_semaphore.h"
  35
  36 static SYNCHHANDLE CleanUp (SYNCHHANDLE hSynch, DWORD Flags);
  37
  38 SYNCHHANDLE CreateSemaphoreCE (
  39
  40    LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,  /* pointer to security attributes */
  41       LONG lInitialCount,   /* initial count */
  42       LONG lMaximumCount,   /* maximum count */
  43       LPCTSTR lpName )
  44
  45 /* Semaphore for use with Windows CE that does not support them directly.
  46    Requires a counter, a mutex to protect the counter, and an
  47    autoreset event.
  48
  49    Here are the rules that must always hold between the autoreset event
  50    and the mutex (any violation of these rules by the CE semaphore functions
  51    will, in all likelihood, result in a defect):
  52     1. No thread can set, pulse, or reset the event,
  53        nor can it access any part of the SYNCHHANDLE structure,
  54        without first gaining ownership of the mutex.
  55        BUT, a thread can wait on the event without owning the mutex
  56        (this is clearly necessary or else the event could never be set).
  57     2. The event is in a signaled state if and only if the current semaphore
  58        count ("CurCount") is greater than zero.
  59     3. The semaphore count is always >= 0 and <= the maximum count */
  60
  61 {
  62    SYNCHHANDLE hSynch = NULL, result = NULL;
  63
  64    __try
  65         {
  66       if (lInitialCount > lMaximumCount || lMaximumCount < 0 || lInitialCount < 0)
  67           {
  68               /* Bad parameters */
  69          SetLastError (SYNCH_ERROR);
  70          __leave;
  71       }
  72
  73       hSynch = HeapAlloc (GetProcessHeap(), HEAP_ZERO_MEMORY, SYNCH_HANDLE_SIZE);
  74       if (hSynch == NULL) __leave;
  75
  76       hSynch->MaxCount = lMaximumCount;
  77       hSynch->CurCount = lInitialCount;
  78       hSynch->lpName = lpName;
  79
  80       hSynch->hMutex = CreateMutex (lpSemaphoreAttributes, FALSE, NULL);
  81
  82       WaitForSingleObject (hSynch->hMutex, INFINITE);
  83       /*  Create the event. It is initially signaled if and only if the
  84           initial count is > 0 */
  85       hSynch->hEvent = CreateEvent (lpSemaphoreAttributes, FALSE,
  86               lInitialCount > 0, NULL);
  87       ReleaseMutex (hSynch->hMutex);
  88       hSynch->hSemph = NULL;
  89    }
  90    __finally
  91    {
  92        /* Return with the handle, or, if there was any error, return
  93         a null after closing any open handles and freeing any allocated memory. */
  94       result=CleanUp(hSynch, 6 /* An event and a mutex, but no semaphore. */);
  95    }
  96
  97    return result;
  98 }
  99
 100 BOOL ReleaseSemaphoreCE (SYNCHHANDLE hSemCE, LONG cReleaseCount, LPLONG lpPreviousCount)
 101 /* Windows CE equivalent to ReleaseSemaphore. */
 102 {
 103    BOOL Result = TRUE;
 104
 105    /* Gain access to the object to assure that the release count
 106       would not cause the total count to exceed the maximum. */
 107
 108    __try
 109    {
 110       WaitForSingleObject (hSemCE->hMutex, INFINITE);
 111           /* reply only if asked to */
 112           if (lpPreviousCount!=NULL)
 113                  *lpPreviousCount = hSemCE->CurCount;
 114       if (hSemCE->CurCount + cReleaseCount > hSemCE->MaxCount || cReleaseCount <= 0)
 115           {
 116          SetLastError (SYNCH_ERROR);
 117          Result = FALSE;
 118          __leave;
 119       }
 120       hSemCE->CurCount += cReleaseCount;
 121
 122       /*  Set the autoreset event, releasing exactly one waiting thread, now or
 123           in the future.  */
 124
 125       SetEvent (hSemCE->hEvent);
 126    }
 127    __finally
 128    {
 129       ReleaseMutex (hSemCE->hMutex);
 130    }
 131
 132    return Result;
 133 }
 134
 135 DWORD WaitForSemaphoreCE (SYNCHHANDLE hSemCE, DWORD dwMilliseconds)
 136    /* Windows CE semaphore equivalent of WaitForSingleObject. */
 137 {
 138    DWORD WaitResult;
 139
 140    WaitResult = WaitForSingleObject (hSemCE->hMutex, dwMilliseconds);
 141    if (WaitResult != WAIT_OBJECT_0 && WaitResult != WAIT_ABANDONED_0) return WaitResult;
 142    while (hSemCE->CurCount <= 0)
 143    {
 144
 145       /* The count is 0, and the thread must wait on the event (which, by
 146          the rules, is currently reset) for semaphore resources to become
 147          available. First, of course, the mutex must be released so that another
 148          thread will be capable of setting the event. */
 149
 150       ReleaseMutex (hSemCE->hMutex);
 151
 152       /*  Wait for the event to be signaled, indicating a semaphore state change.
 153           The event is autoreset and signaled with a SetEvent (not PulseEvent)
 154           so exactly one waiting thread (whether or not there is currently
 155           a waiting thread) is released as a result of the SetEvent. */
 156
 157       WaitResult = WaitForSingleObject (hSemCE->hEvent, dwMilliseconds);
 158       if (WaitResult != WAIT_OBJECT_0) return WaitResult;
 159
 160       /*  This is where the properties of setting of an autoreset event is critical
 161           to assure that, even if the semaphore state changes between the
 162           preceding Wait and the next, and even if NO threads are waiting
 163           on the event at the time of the SetEvent, at least one thread
 164           will be released.
 165           Pulsing a manual reset event would appear to work, but it would have
 166           a defect which could appear if the semaphore state changed between
 167           the two waits. */
 168
 169       WaitResult = WaitForSingleObject (hSemCE->hMutex, dwMilliseconds);
 170       if (WaitResult != WAIT_OBJECT_0 && WaitResult != WAIT_ABANDONED_0) return WaitResult;
 171
 172    }
 173    /* The count is not zero and this thread owns the mutex.  */
 174
 175    hSemCE->CurCount--;
 176    /* The event is now unsignaled, BUT, the semaphore count may not be
 177       zero, in which case the event should be signaled again
 178       before releasing the mutex. */
 179
 180    if (hSemCE->CurCount > 0) SetEvent (hSemCE->hEvent);
 181    ReleaseMutex (hSemCE->hMutex);
 182    return WaitResult;
 183 }
 184
 185 BOOL CloseSynchHandle (SYNCHHANDLE hSynch)
 186 /* Close a synchronization handle.
 187    Improvement: Test for a valid handle before dereferencing the handle. */
 188 {
 189    BOOL Result = TRUE;
 190    if (hSynch->hEvent != NULL) Result = Result && CloseHandle (hSynch->hEvent);
 191    if (hSynch->hMutex != NULL) Result = Result && CloseHandle (hSynch->hMutex);
 192    if (hSynch->hSemph != NULL) Result = Result && CloseHandle (hSynch->hSemph);
 193    HeapFree (GetProcessHeap (), 0, hSynch);
 194    return (Result);
 195 }
 196
 197 static SYNCHHANDLE CleanUp (SYNCHHANDLE hSynch, DWORD Flags)
 198 { /* Prepare to return from a create of a synchronization handle.
 199      If there was any failure, free any allocated resources.
 200      "Flags" indicates which Win32 objects are required in the
 201      synchronization handle. */
 202
 203    BOOL ok = TRUE;
 204
 205    if (hSynch == NULL) return NULL;
 206    if ((Flags & 4) == 1 && (hSynch->hEvent == NULL)) ok = FALSE;
 207    if ((Flags & 2) == 1 && (hSynch->hMutex == NULL)) ok = FALSE;
 208    if ((Flags & 1) == 1 && (hSynch->hEvent == NULL)) ok = FALSE;
 209    if (!ok)
 210    {
 211       CloseSynchHandle (hSynch);
 212       return NULL;
 213    }
 214    /* Everything worked */
 215    return hSynch;
 216 }