lib/windows-once.c

   1 /* Once-only control (native Windows implementation).
   2    Copyright (C) 2005-2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation; either version 2.1 of the
   7    License, or (at your option) any later version.
   8
   9    This file is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2005.
  18    Based on GCC's gthr-win32.h.  */
  19
  20 #include <config.h>
  21
  22 /* Specification.  */
  23 #include "windows-once.h"
  24
  25 #include <stdlib.h>
  26
  27 void
  28 glwthread_once (glwthread_once_t *once_control, void (*initfunction) (void))
  29 {
  30   if (once_control->inited <= 0)
  31     {
  32       InterlockedIncrement (&once_control->num_threads);
  33       /* If once_control->started is == -1, set it to 0.  */
  34       if (InterlockedCompareExchange (&once_control->started, 0, -1) < 0)
  35         {
  36           /* This thread is the first one to come to this once_control.  */
  37           InitializeCriticalSection (&once_control->lock);
  38           EnterCriticalSection (&once_control->lock);
  39           once_control->inited = 0;
  40           initfunction ();
  41           once_control->inited = 1;
  42           LeaveCriticalSection (&once_control->lock);
  43         }
  44       else
  45         {
  46           /* Some other thread has already started the initialization.
  47              Yield the CPU while waiting for the other thread to finish
  48              initializing and taking the lock.  */
  49           while (once_control->inited < 0)
  50             Sleep (0);
  51           if (once_control->inited <= 0)
  52             {
  53               /* Take the lock.  This blocks until the other thread has
  54                  finished calling the initfunction.  */
  55               EnterCriticalSection (&once_control->lock);
  56               LeaveCriticalSection (&once_control->lock);
  57               if (!(once_control->inited > 0))
  58                 abort ();
  59             }
  60         }
  61       /* Here once_control->started == 0 and once_control->inited > 0.  */
  62       if (InterlockedDecrement (&once_control->num_threads) == 0)
  63         /* once_control->num_threads is now zero, and
  64            once_control->started == 0 and once_control->inited > 0.
  65            No other thread will need to use the lock.
  66            We can therefore destroy the lock, to free resources.  */
  67         /* If once_control->inited is == 1, set it to 2.  */
  68         if (InterlockedCompareExchange (&once_control->inited, 2, 1) == 1)
  69           DeleteCriticalSection (&once_control->lock);
  70     }
  71   /* Proof of correctness:
  72      * num_threads is incremented and then decremented by some threads.
  73        Therefore, num_threads always stays >= 0, and is == 0 at the end.
  74      * The first thread to go through the once_control->started fence
  75        initializes the lock and moves inited from <= 0 to > 0.  The other
  76        threads don't move inited from <= 0 to > 0.
  77      * started, once == 0, stays == 0.
  78      * inited, once > 0, stays > 0 (since at the place where it is assigned 0,
  79        it cannot be > 0).
  80      * inited does not change any more once it is 2.
  81        Therefore, it can be changed from 1 to 2 only once.
  82      * DeleteCriticalSection gets invoked right after inited has been changed
  83        from 1 to 2.  Therefore, DeleteCriticalSection gets invoked only once.
  84      * After a moment where num_threads was 0 and started was 0 and
  85        inited was > 0, no thread can reach an InitializeCriticalSection or
  86        EnterCriticalSection invocation.  Proof:
  87        - At such a moment, no thread is in the code range between
  88            InterlockedIncrement (&once_control->num_threads)
  89          and
  90            InterlockedDecrement (&once_control->num_threads)
  91        - After such a moment, some thread can increment num_threads, but from
  92          there they cannot reach the InitializeCriticalSection invocation,
  93          because the once_control->started test prevents that, and they cannot
  94          reach the EnterCriticalSection invocation in the other branch because
  95          the
  96            if (once_control->inited <= 0)
  97          test prevents that.
  98      * From this it follows that:
  99        - DeleteCriticalSection cannot be executed while the lock is taken
 100          (because DeleteCriticalSection is only executed after a moment where
 101          num_threads was 0 and started was 0 and inited was > 0).
 102        - Once DeleteCriticalSection has been executed, the lock is not used any
 103          more.
 104    */
 105 }