/* * 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 */