source/modules/juce_core/threads/juce_ThreadLocalValue.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /**
  28     Provides cross-platform support for thread-local objects.
  29
  30     This class holds an internal list of objects of the templated type, keeping
  31     an instance for each thread that requests one. The first time a thread attempts
  32     to access its value, an object is created and added to the list for that thread.
  33
  34     Typically, you'll probably want to create a static instance of a ThreadLocalValue
  35     object, or hold one within a singleton.
  36
  37     The templated class for your value must be a primitive type, or a simple POD struct.
  38
  39     When a thread no longer needs to use its value, it can call releaseCurrentThreadStorage()
  40     to allow the storage to be re-used by another thread. If a thread exits without calling
  41     this method, the object storage will be left allocated until the ThreadLocalValue object
  42     is deleted.
  43
  44     @tags{Core}
  45 */
  46 template <typename Type>
  47 class ThreadLocalValue
  48 {
  49 public:
  50     /** */
  51     ThreadLocalValue() = default;
  52
  53     /** Destructor.
  54         When this object is deleted, all the value objects for all threads will be deleted.
  55     */
  56     ~ThreadLocalValue()
  57     {
  58         for (auto* o = first.get(); o != nullptr;)
  59         {
  60             auto* next = o->next;
  61             delete o;
  62             o = next;
  63         }
  64     }
  65
  66     /** Returns a reference to this thread's instance of the value.
  67         Note that the first time a thread tries to access the value, an instance of the
  68         value object will be created - so if your value's class has a non-trivial
  69         constructor, be aware that this method could invoke it.
  70     */
  71     Type& operator*() const noexcept                        { return get(); }
  72
  73     /** Returns a pointer to this thread's instance of the value.
  74         Note that the first time a thread tries to access the value, an instance of the
  75         value object will be created - so if your value's class has a non-trivial
  76         constructor, be aware that this method could invoke it.
  77     */
  78     operator Type*() const noexcept                         { return &get(); }
  79
  80     /** Accesses a method or field of the value object.
  81         Note that the first time a thread tries to access the value, an instance of the
  82         value object will be created - so if your value's class has a non-trivial
  83         constructor, be aware that this method could invoke it.
  84     */
  85     Type* operator->() const noexcept                       { return &get(); }
  86
  87     /** Assigns a new value to the thread-local object. */
  88     ThreadLocalValue& operator= (const Type& newValue)      { get() = newValue; return *this; }
  89
  90     /** Returns a reference to this thread's instance of the value.
  91         Note that the first time a thread tries to access the value, an instance of the
  92         value object will be created - so if your value's class has a non-trivial
  93         constructor, be aware that this method could invoke it.
  94     */
  95     Type& get() const noexcept
  96     {
  97         auto threadId = Thread::getCurrentThreadId();
  98         ObjectHolder* o = nullptr;
  99
 100         for (o = first.get(); o != nullptr; o = o->next)
 101             if (o->threadId.get() == threadId)
 102                 return o->object;
 103
 104         for (o = first.get(); o != nullptr; o = o->next)
 105             if (o->threadId.compareAndSetBool (threadId, nullptr))
 106                 break;
 107
 108         if (o != nullptr)
 109             o->object = Type();
 110         else
 111             for (o = new ObjectHolder (threadId, first.get());
 112                  ! first.compareAndSetBool (o, o->next);
 113                  o->next = first.get());
 114
 115         return o->object;
 116     }
 117
 118     /** Called by a thread before it terminates, to allow this class to release
 119         any storage associated with the thread.
 120     */
 121     void releaseCurrentThreadStorage()
 122     {
 123         auto threadId = Thread::getCurrentThreadId();
 124
 125         for (auto* o = first.get(); o != nullptr; o = o->next)
 126             if (o->threadId.compareAndSetBool (nullptr, threadId))
 127                 return;
 128     }
 129
 130 private:
 131     //==============================================================================
 132     struct ObjectHolder
 133     {
 134         ObjectHolder (Thread::ThreadID idToUse, ObjectHolder* n) : threadId (idToUse), next (n), object() {}
 135
 136         Atomic<Thread::ThreadID> threadId;
 137         ObjectHolder* next;
 138         Type object;
 139
 140         JUCE_DECLARE_NON_COPYABLE (ObjectHolder)
 141     };
 142
 143     mutable Atomic<ObjectHolder*> first;
 144
 145     JUCE_DECLARE_NON_COPYABLE (ThreadLocalValue)
 146 };
 147
 148 } // namespace juce