/*
* pthread_once.c
*
* Description:
* This translation unit implements miscellaneous thread functions.
*
* --------------------------------------------------------------------------
*
* Pthreads-win32 - POSIX Threads Library for Win32
* Copyright(C) 1998 John E. Bossom
* Copyright(C) 1999,2005 Pthreads-win32 contributors
*
* Contact Email: rpj@callisto.canberra.edu.au
*
* The current list of contributors is contained
* in the file CONTRIBUTORS included with the source
* code distribution. The list can also be seen at the
* following World Wide Web location:
* http://sources.redhat.com/pthreads-win32/contributors.html
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library in the file COPYING.LIB;
* if not, write to the Free Software Foundation, Inc.,
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
*/
/*
* NOTES:
* pthread_once() performs a very simple task. So why is this implementation
* so complicated?
*
* The original implementation WAS very simple, but it relied on Windows random
* priority boosting to resolve starvation problems. Windows priority boosting
* does not occur for realtime priority classes (levels 16 to 31).
*
* You can check back to previous versions of code in the CVS repository or
* search the mailing list archives for discussion.
*
* Version A
* ---------
* Waiting threads would resume and suspend again using Sleep(0) until the
* init_routine had completed, but a higher priority waiter could hog the CPU and
* starve the initter thread until Windows randomly boosted it's priority, or forever
* for realtime applications.
*
* Version B
* ---------
* This was fixed by introducing a per once_control manual-reset event that is
* created and destroyed dynamically only if there are waiters. The design did not
* need global critical sections. Each once_control remained independent. A waiter
* could be confident that if the event was not null then it did not need to create
* the event.
*
* Version C
* ---------
* Since a change in ABI would result from version B, it was decided to take
* the opportunity and make pthread_once() fully compliant with the Single Unix
* Specification (version 3 at the time). This required allowing the init_routine
* to be a cancelation point. A cancelation meant that at least some waiting threads
* if any had to be woken so that one might become the new initter thread.
* Waiters could no longer simply assume that, if the event was not null, it did
* not need to create an event.
*
* Also, the cancelled init thread needed to set the event, and the
* new init thread (the winner of the race between any newly arriving threads and
* waking waiters) would need to reset it again. In the meantime, threads could be
* happily looping around until they either suspended on the reset event, or exited
* because the init thread had completed. It was also once again possible for a higher
* priority waiter to starve the init thread.
*
* Version D
* ---------
* There were now two options considered:
* - use an auto-reset event; OR
* - add our own priority boosting.
*
* An auto-reset event would stop threads from looping ok, but it makes threads
* dependent on earlier threads to successfully set the event in turn when it's time
* to wake up, and this serialises threads unecessarily on MP systems. It also adds
* an extra kernel call for each waking thread. If one waiter wakes and dies (async
* cancelled or killed) before it can set the event, then all remaining waiters are
* stranded.
*
* Priority boosting is a standard method for solving priority inversion and
* starvation problems. Furthermore, all of the priority boost logic can
* be restricted to the post cancellation tracks. That is, it need not slow
* the normal cancel-free behaviour. Threads remain independent of other threads.
*
* The implementation below adds only a few local (to the thread) integer comparisons
* to the normal track through the routine and additional bus locking/cache line
* syncing operations have been avoided altogether in the uncontended track.
*/
#include "pthread.h"
#include "implement.h"
static void PTW32_CDECL
ptw32_once_init_routine_cleanup(void * arg)
{
pthread_once_t * once_control = (pthread_once_t *) arg;
(void) PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->state, (LONG)PTW32_ONCE_CANCELLED);
(void) PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->started, (LONG)PTW32_FALSE);
if (InterlockedExchangeAdd((LPLONG)&once_control->event, 0L)) /* MBR fence */
{
int lasterror = GetLastError ();
int lastWSAerror = WSAGetLastError ();
/*
* There are waiters, wake some up.
*/
if (!SetEvent(once_control->event))
{
SetLastError (lasterror);
WSASetLastError (lastWSAerror);
}
}
}
int
pthread_once (pthread_once_t * once_control, void (*init_routine) (void))
/*
* ------------------------------------------------------
* DOCPUBLIC
* If any thread in a process with a once_control parameter
* makes a call to pthread_once(), the first call will summon
* the init_routine(), but subsequent calls will not. The
* once_control parameter determines whether the associated
* initialization routine has been called. The init_routine()
* is complete upon return of pthread_once().
* This function guarantees that one and only one thread
* executes the initialization routine, init_routine when
* access is controlled by the pthread_once_t control
* key.
*
* pthread_once() is not a cancelation point, but the init_routine
* can be. If it's cancelled then the effect on the once_control is
* as if pthread_once had never been entered.
*
*
* PARAMETERS
* once_control
* pointer to an instance of pthread_once_t
*
* init_routine
* pointer to an initialization routine
*
*
* DESCRIPTION
* See above.
*
* RESULTS
* 0 success,
* EINVAL once_control or init_routine is NULL
*
* ------------------------------------------------------
*/
{
int result;
int lasterror;
int lastWSAerror;
int restoreLastError;
LONG state;
pthread_t self;
HANDLE w32Thread = 0;
if (once_control == NULL || init_routine == NULL)
{
result = EINVAL;
goto FAIL0;
}
else
{
result = 0;
}
/*
* We want to be invisible to GetLastError() outside of this routine.
*/
lasterror = GetLastError ();
lastWSAerror = WSAGetLastError ();
restoreLastError = PTW32_FALSE;
while (!((state = InterlockedExchangeAdd((LPLONG)&once_control->state, 0L)) /* Atomic Read */
& (LONG)PTW32_ONCE_DONE))
{
LONG cancelled = (state & PTW32_ONCE_CANCELLED);
if (cancelled)
{
/* Boost priority momentarily */
if (!w32Thread)
{
self = pthread_self();
w32Thread = ((ptw32_thread_t *)self.p)->threadH;
}
/*
* Prevent pthread_setschedparam() from changing our priority while we're boosted.
*/
pthread_mutex_lock(&((ptw32_thread_t *)self.p)->threadLock);
SetThreadPriority(w32Thread, THREAD_PRIORITY_HIGHEST);
}
if (!PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->started, (LONG)PTW32_TRUE))
{
if (cancelled)
{
/*
* The previous initter was cancelled.
* We now have a new initter (us) and we need to make the rest wait again.
* Furthermore, we're running at max priority until after we've reset the event
* so we will not be starved by any other threads that may now be looping
* around.
*/
if (InterlockedExchangeAdd((LPLONG)&once_control->event, 0L)) /* MBR fence */
{
if (!ResetEvent(once_control->event))
{
restoreLastError = PTW32_TRUE;
}
}
/*
* Any threads entering the wait section and getting out again before
* the event is reset and the CANCELLED state is cleared will, at worst,
* just go around again or, if they suspend and we (the initter) completes before
* they resume, they will see state == DONE and leave immediately.
*/
PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->state, (LONG)PTW32_ONCE_CLEAR);
/*
* Restore priority. We catch any changes to this thread's priority
* only if they were done through the POSIX API (i.e. pthread_setschedparam)
*/
SetThreadPriority(w32Thread, ((ptw32_thread_t *)self.p)->sched_priority);
pthread_mutex_unlock(&((ptw32_thread_t *)self.p)->threadLock);
}
#ifdef _MSC_VER
#pragma inline_depth(0)
#endif
pthread_cleanup_push(ptw32_once_init_routine_cleanup, (void *) once_control);
(*init_routine)();
pthread_cleanup_pop(0);
#ifdef _MSC_VER
#pragma inline_depth()
#endif
(void) PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->state, (LONG)PTW32_ONCE_DONE);
/*
* we didn't create the event.
* it is only there if there is someone waiting.
* Avoid using the global event_lock but still prevent SetEvent
* from overwriting any 'lasterror' if the event is closed before we
* are done with it.
*/
if (InterlockedExchangeAdd((LPLONG)&once_control->event, 0L)) /* MBR fence */
{
if (!SetEvent(once_control->event))
{
restoreLastError = PTW32_TRUE;
}
}
}
else
{
HANDLE tmpEvent;
if (cancelled)
{
/*
* Restore priority. We catch any changes to this thread's priority
* only if they were done through the POSIX API (i.e. pthread_setschedparam.
*/
SetThreadPriority(w32Thread, ((ptw32_thread_t *)self.p)->sched_priority);
pthread_mutex_unlock(&((ptw32_thread_t *)self.p)->threadLock);
}
/*
* wait for init.
* while waiting, create an event to wait on
*/
if (1 == InterlockedIncrement((LPLONG)&once_control->eventUsers))
{
/*
* RE CANCELLATION:
* If we are the first thread after the initter thread, and the init_routine is cancelled
* while we're suspended at this point in the code:-
* - state will not get set to PTW32_ONCE_DONE;
* - cleanup will not see an event and cannot set it;
* - therefore, we will eventually resume, create an event and wait on it;
* cleanup will set state == CANCELLED before checking for an event, so that
* we will see it and avoid waiting (as for state == DONE). We will go around again and
* we may then become the initter.
* If we are still the only other thread when we get to the end of this block, we will
* have closed the event (good). If another thread beats us to be initter, then we will
* re-enter here (good). In case the old event is reused, the event is always reset by
* the new initter before clearing the CANCELLED state, causing any threads that are
* cycling around the loop to wait again.
* The initter thread is guaranteed to be at equal or higher priority than any waiters
* so no waiters will starve the initter, which might otherwise cause us to loop
* forever.
*/
tmpEvent = CreateEvent(NULL, PTW32_TRUE, PTW32_FALSE, NULL);
if (PTW32_INTERLOCKED_COMPARE_EXCHANGE((PTW32_INTERLOCKED_LPLONG)&once_control->event,
(PTW32_INTERLOCKED_LONG)tmpEvent,
(PTW32_INTERLOCKED_LONG)0))
{
CloseHandle(tmpEvent);
}
}
/*
* Check 'state' again in case the initting thread has finished or cancelled
* and left before seeing that there was an event to trigger.
*/
switch (InterlockedExchangeAdd((LPLONG)&once_control->state, 0L))
{
case PTW32_ONCE_CLEAR:
{
/* Neither DONE nor CANCELLED */
if (WAIT_FAILED == WaitForSingleObject(once_control->event, INFINITE))
{
restoreLastError = PTW32_TRUE;
/*
* If the wait failed it's probably because the event is invalid.
* That's possible after a cancellation (but rare) if we got through the
* event create block above while a woken thread was suspended between
* the decrement and exchange below and then resumed before we could wait.
* So we'll yield.
*/
Sleep(0);
}
break;
}
case PTW32_ONCE_CANCELLED:
{
if (once_control->started)
{
/* The new initter hasn't cleared the cancellation yet, so give the
* processor to a more productive thread. */
Sleep(0);
}
break;
}
}
/* last one out shut off the lights */
if (0 == InterlockedDecrement((LPLONG)&once_control->eventUsers))
{
/* we were last */
if ((tmpEvent = (HANDLE)
PTW32_INTERLOCKED_EXCHANGE((LPLONG)&once_control->event,
(LONG)0)))
{
CloseHandle(tmpEvent);
}
}
}
}
if (restoreLastError)
{
SetLastError (lasterror);
WSASetLastError (lastWSAerror);
}
/*
* ------------
* Failure Code
* ------------
*/
FAIL0:
return (result);
} /* pthread_once */