1 /***************************************************************************** 2 3 Copyright (c) 2014, 2018, Oracle and/or its affiliates. All Rights Reserved. 4 5 This program is free software; you can redistribute it and/or modify it under 6 the terms of the GNU General Public License, version 2.0, as published by the 7 Free Software Foundation. 8 9 This program is also distributed with certain software (including but not 10 limited to OpenSSL) that is licensed under separate terms, as designated in a 11 particular file or component or in included license documentation. The authors 12 of MySQL hereby grant you an additional permission to link the program and 13 your derivative works with the separately licensed software that they have 14 included with MySQL. 15 16 This program is distributed in the hope that it will be useful, but WITHOUT 17 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 18 FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, 19 for more details. 20 21 You should have received a copy of the GNU General Public License along with 22 this program; if not, write to the Free Software Foundation, Inc., 23 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 24 25 *****************************************************************************/ 26 27 /** @file include/os0once.h 28 A class that aids executing a given function exactly once in a multi-threaded 29 environment. 30 31 Created Feb 20, 2014 Vasil Dimov 32 *******************************************************/ 33 34 #ifndef os0once_h 35 #define os0once_h 36 37 #include "univ.i" 38 39 #include "os0atomic.h" 40 #include "ut0ut.h" 41 42 /** Execute a given function exactly once in a multi-threaded environment 43 or wait for the function to be executed by another thread. 44 45 Example usage: 46 First the user must create a control variable of type os_once::state_t and 47 assign it os_once::NEVER_DONE. 48 Then the user must pass this variable, together with a function to be 49 executed to os_once::do_or_wait_for_done(). 50 51 Multiple threads can call os_once::do_or_wait_for_done() simultaneously with 52 the same (os_once::state_t) control variable. The provided function will be 53 called exactly once and when os_once::do_or_wait_for_done() returns then this 54 function has completed execution, by this or another thread. In other words 55 os_once::do_or_wait_for_done() will either execute the provided function or 56 will wait for its execution to complete if it is already called by another 57 thread or will do nothing if the function has already completed its execution 58 earlier. 59 60 This mimics pthread_once(3), but unfortunatelly pthread_once(3) does not 61 support passing arguments to the init_routine() function. We should use 62 std::call_once() when we start compiling with C++11 enabled. */ 63 class os_once { 64 public: 65 /** Control variables' state type */ 66 typedef ib_uint32_t state_t; 67 68 /** Not yet executed. */ 69 static const state_t NEVER_DONE = 0; 70 71 /** Currently being executed by this or another thread. */ 72 static const state_t IN_PROGRESS = 1; 73 74 /** Finished execution. */ 75 static const state_t DONE = 2; 76 77 /** Call a given function or wait its execution to complete if it is 78 already called by another thread. 79 @param[in,out] state control variable 80 @param[in] do_func function to call 81 @param[in,out] do_func_arg an argument to pass to do_func(). */ do_or_wait_for_done(volatile state_t * state,void (* do_func)(void *),void * do_func_arg)82 static void do_or_wait_for_done(volatile state_t *state, 83 void (*do_func)(void *), void *do_func_arg) { 84 /* Avoid calling os_compare_and_swap_uint32() in the most 85 common case. */ 86 if (*state == DONE) { 87 return; 88 } 89 90 if (os_compare_and_swap_uint32(state, NEVER_DONE, IN_PROGRESS)) { 91 /* We are the first. Call the function. */ 92 93 do_func(do_func_arg); 94 95 const bool swapped = os_compare_and_swap_uint32(state, IN_PROGRESS, DONE); 96 97 ut_a(swapped); 98 } else { 99 /* The state is not NEVER_DONE, so either it is 100 IN_PROGRESS (somebody is calling the function right 101 now or DONE (it has already been called and completed). 102 Wait for it to become DONE. */ 103 for (;;) { 104 const state_t s = *state; 105 106 switch (s) { 107 case DONE: 108 return; 109 case IN_PROGRESS: 110 break; 111 case NEVER_DONE: 112 /* fall through */ 113 default: 114 ut_error; 115 } 116 117 #ifndef UNIV_HOTBACKUP 118 UT_RELAX_CPU(); 119 #endif /* !UNIV_HOTBACKUP */ 120 } 121 } 122 } 123 }; 124 125 #endif /* os0once_h */ 126