mono/utils/mono-lazy-init.h

   1 /**
   2  * \file
   3  * Lazy initialization and cleanup utilities
   4  *
   5  * Authors: Ludovic Henry <ludovic@xamarin.com>
   6  *
   7  * Copyright 2015 Xamarin, Inc. (www.xamarin.com)
   8  * Licensed under the MIT license. See LICENSE file in the project root for full license information.
   9  */
  10
  11 #ifndef __MONO_LAZY_INIT_H__
  12 #define __MONO_LAZY_INIT_H__
  13
  14 #include <glib.h>
  15
  16 #include <config.h>
  17
  18 #include "atomic.h"
  19 #include "mono-threads.h"
  20 #include "mono-memory-model.h"
  21
  22 /*
  23  * These functions should be used if you want some form of lazy initialization. You can have a look at the
  24  * threadpool for a more detailed example.
  25  *
  26  * The idea is that a module can be in 5 different states:
  27  *  - not initialized: it is the first state it starts in
  28  *  - initializing/initialized: whenever we need this module for the first time, we need to initialize it: allocate
  29  *     memory, launch background thread, etc. To achieve this, we have a module specific function (let's call it
  30  *     initialize)
  31  *  - cleaning/cleaned: when we want to clean this module specific data up, then we need to clean it up: deallocate
  32  *     memory, wait for background threads to finish, etc. As for the initialization process, we need a module specific
  33  *     function (let's call it cleanup)
  34  *
  35  * The switch from one state to the other can only happen in the following ways:
  36  *  - not initialized
  37  *  - not initialized -> initializing -> initialized
  38  *  - not initialized -> cleaned
  39  *  - not initialized -> initializing -> initialized -> cleaning -> cleaned
  40  *
  41  * The initialize and cleanup functions are guaranteed to:
  42  *  - be each called once and only once
  43  *  - not be called concurrently (either 2+ initialize or 2+ cleanup, either initialize and cleanup)
  44  */
  45
  46 typedef volatile gint32 mono_lazy_init_t;
  47
  48 enum {
  49         MONO_LAZY_INIT_STATUS_NOT_INITIALIZED,
  50         MONO_LAZY_INIT_STATUS_INITIALIZING,
  51         MONO_LAZY_INIT_STATUS_INITIALIZED,
  52         MONO_LAZY_INIT_STATUS_CLEANING,
  53         MONO_LAZY_INIT_STATUS_CLEANED,
  54 };
  55
  56 static inline gboolean
  57 mono_lazy_initialize (mono_lazy_init_t *lazy_init, void (*initialize) (void))
  58 {
  59         gint32 status;
  60
  61         g_assert (lazy_init);
  62
  63         status = *lazy_init;
  64
  65         // This barrier might be redundant with volatile.
  66         //
  67         // Without either, code in our caller can
  68         // read state ahead of the call to mono_lazy_initialize,
  69         // and ahead of the call to initialize.
  70         //
  71         // Recall that barriers come in pairs.
  72         // One barrier is in mono_atomic_cas_i32 below.
  73         // This is the other.
  74         //
  75         // A common case of initializing a pointer, that
  76         // the reader dereferences, is ok,
  77         // on most architectures (not Alpha), due to "data dependency".
  78         //
  79         // But if the caller is merely reading globals, that initialize writes,
  80         // then those reads can run ahead of initialize and be incorrect.
  81         //
  82         // On-demand initialization is much tricker than generally understood.
  83         //
  84         // Strongly consider adapting:
  85         //   http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2660.htm
  86         //
  87         // At the very bottom. After making it coop-friendly.
  88         //
  89         // In particular, it eliminates the barriers from the fast path.
  90         // At the cost of a thread local access.
  91         //
  92         // The thread local access should be "gamed" (forced to initialize
  93         // early on platforms that do on-demand initialization), by inserting
  94         // an extra use early in runtime initialization. i.e. so it does not
  95         // take any locks, and become coop-unfriendly.
  96         //
  97         mono_memory_read_barrier ();
  98
  99         if (status >= MONO_LAZY_INIT_STATUS_INITIALIZED)
 100                 return status == MONO_LAZY_INIT_STATUS_INITIALIZED;
 101
 102         if (status == MONO_LAZY_INIT_STATUS_INITIALIZING
 103              || mono_atomic_cas_i32 (lazy_init, MONO_LAZY_INIT_STATUS_INITIALIZING, MONO_LAZY_INIT_STATUS_NOT_INITIALIZED)
 104                  != MONO_LAZY_INIT_STATUS_NOT_INITIALIZED
 105         ) {
 106                 // FIXME: This is not coop-friendly.
 107                 while (*lazy_init == MONO_LAZY_INIT_STATUS_INITIALIZING)
 108                         mono_thread_info_yield ();
 109
 110                 g_assert (mono_atomic_load_i32 (lazy_init) >= MONO_LAZY_INIT_STATUS_INITIALIZED);
 111
 112                 // This result is transient. Another thread can proceed to cleanup.
 113                 // Perhaps cleanup should not be attempted, just on-demand initialization.
 114                 return *lazy_init == MONO_LAZY_INIT_STATUS_INITIALIZED;
 115         }
 116
 117         initialize ();
 118
 119         mono_atomic_store_release (lazy_init, MONO_LAZY_INIT_STATUS_INITIALIZED);
 120
 121         // This result is transient. Another thread can proceed to cleanup.
 122         // Perhaps cleanup should not be attempted, just on-demand initialization.
 123         return TRUE;
 124 }
 125
 126 static inline void
 127 mono_lazy_cleanup (mono_lazy_init_t *lazy_init, void (*cleanup) (void))
 128 {
 129         gint32 status;
 130
 131         g_assert (lazy_init);
 132
 133         status = *lazy_init;
 134
 135         if (status == MONO_LAZY_INIT_STATUS_NOT_INITIALIZED
 136              && mono_atomic_cas_i32 (lazy_init, MONO_LAZY_INIT_STATUS_CLEANED, MONO_LAZY_INIT_STATUS_NOT_INITIALIZED)
 137                  == MONO_LAZY_INIT_STATUS_NOT_INITIALIZED
 138         ) {
 139                 return;
 140         }
 141         if (status == MONO_LAZY_INIT_STATUS_INITIALIZING) {
 142                 while ((status = *lazy_init) == MONO_LAZY_INIT_STATUS_INITIALIZING)
 143                         mono_thread_info_yield ();
 144         }
 145
 146         if (status == MONO_LAZY_INIT_STATUS_CLEANED)
 147                 return;
 148         if (status == MONO_LAZY_INIT_STATUS_CLEANING
 149              || mono_atomic_cas_i32 (lazy_init, MONO_LAZY_INIT_STATUS_CLEANING, MONO_LAZY_INIT_STATUS_INITIALIZED)
 150                  != MONO_LAZY_INIT_STATUS_INITIALIZED
 151         ) {
 152                 while (*lazy_init == MONO_LAZY_INIT_STATUS_CLEANING)
 153                         mono_thread_info_yield ();
 154                 g_assert (mono_atomic_load_i32 (lazy_init) == MONO_LAZY_INIT_STATUS_CLEANED);
 155                 return;
 156         }
 157
 158         cleanup ();
 159
 160         mono_atomic_store_release (lazy_init, MONO_LAZY_INIT_STATUS_CLEANED);
 161 }
 162
 163 static inline gboolean
 164 mono_lazy_is_initialized (mono_lazy_init_t *lazy_init)
 165 {
 166         g_assert (lazy_init);
 167         return mono_atomic_load_i32 (lazy_init) == MONO_LAZY_INIT_STATUS_INITIALIZED;
 168 }
 169
 170 #endif