common/JackAtomicArrayState.h

   1 /*
   2 Copyright (C) 2004-2006 Grame
   3
   4 This program is free software; you can redistribute it and/or modify
   5 it under the terms of the GNU General Public License as published by
   6 the Free Software Foundation; either version 2 of the License, or
   7 (at your option) any later version.
   8
   9 This program 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 General Public License for more details.
  13
  14 You should have received a copy of the GNU General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef __JackAtomicArrayState__
  21 #define __JackAtomicArrayState__
  22
  23 #include "JackAtomic.h"
  24 #include "JackError.h"
  25 #include <string.h> // for memcpy
  26
  27 namespace Jack
  28 {
  29
  30 /*!
  31 \brief Counter for CAS
  32 */
  33
  34 struct AtomicArrayCounter
  35 {
  36     union {
  37         struct {
  38             unsigned char fByteVal[4];
  39         }
  40         scounter;
  41         UInt32 fLongVal;
  42     }info;
  43
  44     AtomicArrayCounter& operator=(volatile AtomicArrayCounter& obj)
  45     {
  46         info.fLongVal = obj.info.fLongVal;
  47         return *this;
  48     }
  49 };
  50
  51 #define Counter1(e) (e).info.fLongVal
  52 #define GetIndex1(e, state) ((e).info.scounter.fByteVal[state])
  53 #define SetIndex1(e, state, val) ((e).info.scounter.fByteVal[state] = val)
  54 #define IncIndex1(e, state) ((e).info.scounter.fByteVal[state]++)
  55 #define SwapIndex1(e, state) (((e).info.scounter.fByteVal[0] == state) ? 0 : state)
  56
  57 /*!
  58 \brief A class to handle several states in a lock-free manner
  59
  60 Requirement:
  61
  62         - a "current" state
  63         - several possible "pending" state
  64         - an TrySwitchState(int state) operation to atomically switch a "pending" to the "current" state (the pending becomes the current).
  65
  66         The TrySwitchState operation returns a "current" state (either the same if switch fails or the new one, one can know if the switch has succeeded)
  67
  68         - a WriteNextStartState(int state) returns a "pending" state to be written into
  69         - a WriteNextStartStop(int state) make the written "pending" state become "switchable"
  70
  71         Different pending states can be written independantly and concurrently.
  72
  73         GetCurrentIndex() *must* return an increasing value to be able to check reading current state coherency
  74
  75         The fCounter is an array of indexes to access the current and 3 different "pending" states.
  76
  77         ¥ WriteNextStateStart(int index) must return a valid state to be written into, and must invalidate state "index" ==> cur state switch.
  78         ¥ WriteNextStateStop(int index) makes the "index" state become "switchable" with the current state.
  79         ¥ TrySwitchState(int index) must detect that pending state is a new state, and does the switch
  80         ¥ ReadCurrentState() must return the state
  81         ¥ GetCurrentIndex() must return an index increased each new switch.
  82         ¥ WriteNextStateStart(int index1) and WriteNextStateStart(int index2) can be interleaved
  83
  84         [switch counter][index state][index state][cur index]
  85
  86 */
  87
  88 // CHECK livelock
  89
  90 template <class T>
  91 class JackAtomicArrayState
  92 {
  93
  94     protected:
  95
  96         // fState[0] ==> current
  97         // fState[1] ==> pending
  98         // fState[2] ==> request
  99
 100         T fState[3];
 101         volatile AtomicArrayCounter fCounter;
 102
 103         UInt32 WriteNextStateStartAux(int state, bool* result)
 104         {
 105             AtomicArrayCounter old_val;
 106             AtomicArrayCounter new_val;
 107             UInt32 cur_index;
 108             UInt32 next_index;
 109             bool need_copy;
 110             do {
 111                 old_val = fCounter;
 112                 new_val = old_val;
 113                 *result = GetIndex1(new_val, state);
 114                 cur_index = GetIndex1(new_val, 0);
 115                 next_index = SwapIndex1(fCounter, state);
 116                 need_copy = (GetIndex1(new_val, state) == 0);   // Written = false, switch just occured
 117                 SetIndex1(new_val, state, 0);                                   // Written = false, invalidate state
 118             } while (!CAS(Counter1(old_val), Counter1(new_val), (UInt32*)&fCounter));
 119             if (need_copy)
 120                 memcpy(&fState[next_index], &fState[cur_index], sizeof(T));
 121             return next_index;
 122         }
 123
 124         void WriteNextStateStopAux(int state)
 125         {
 126             AtomicArrayCounter old_val;
 127             AtomicArrayCounter new_val;
 128             do {
 129                 old_val = fCounter;
 130                 new_val = old_val;
 131                 SetIndex1(new_val, state, 1);  // Written = true, state becomes "switchable"
 132             } while (!CAS(Counter1(old_val), Counter1(new_val), (UInt32*)&fCounter));
 133         }
 134
 135     public:
 136
 137         JackAtomicArrayState()
 138         {
 139             JackLog("JackAtomicArrayState constructor\n");
 140             Counter1(fCounter) = 0;
 141         }
 142
 143         ~JackAtomicArrayState() // Not virtual ??
 144         {}
 145
 146         /*!
 147         \brief Returns the current state : only valid in the RT reader thread
 148         */
 149
 150         T* ReadCurrentState()
 151         {
 152             return &fState[GetIndex1(fCounter, 0)];
 153         }
 154
 155         /*!
 156         \brief Returns the current switch counter
 157         */
 158
 159         UInt16 GetCurrentIndex()
 160         {
 161             return GetIndex1(fCounter, 3);
 162         }
 163
 164         /*!
 165                 \brief Tries to switch to the next state and returns the new current state (either the same as before if case of switch failure or the new one)
 166                 */
 167
 168         T* TrySwitchState(int state)
 169         {
 170             AtomicArrayCounter old_val;
 171             AtomicArrayCounter new_val;
 172             do {
 173                 old_val = fCounter;
 174                 new_val = old_val;
 175                 if (GetIndex1(new_val, state)) {                                                // If state has been written
 176                     SetIndex1(new_val, 0, SwapIndex1(new_val, state));  // Prepare switch
 177                     SetIndex1(new_val, state, 0);                                               // Invalidate the state "state"
 178                     IncIndex1(new_val, 3);                                                              // Inc switch
 179                 }
 180             } while (!CAS(Counter1(old_val), Counter1(new_val), (UInt32*)&fCounter));
 181             return &fState[GetIndex1(fCounter, 0)];     // Read the counter again
 182         }
 183
 184         /*!
 185         \brief Tries to switch to the next state and returns the new current state (either the same as before if case of switch failure or the new one)
 186         */
 187
 188         T* TrySwitchState(int state, bool* result)
 189         {
 190             AtomicArrayCounter old_val;
 191             AtomicArrayCounter new_val;
 192             do {
 193                 old_val = fCounter;
 194                 new_val = old_val;
 195                 if ((*result = GetIndex1(new_val, state))) {                    // If state has been written
 196                     SetIndex1(new_val, 0, SwapIndex1(new_val, state));  // Prepare switch
 197                     SetIndex1(new_val, state, 0);                                               // Invalidate the state "state"
 198                     IncIndex1(new_val, 3);                                                              // Inc switch
 199                 }
 200             } while (!CAS(Counter1(old_val), Counter1(new_val), (UInt32*)&fCounter));
 201             return &fState[GetIndex1(fCounter, 0)];     // Read the counter again
 202         }
 203
 204         /*!
 205                 \brief Start write operation : setup and returns the next state to update, check for recursive write calls.
 206                 */
 207
 208         T* WriteNextStateStart(int state)
 209         {
 210             bool tmp;
 211             UInt32 index = WriteNextStateStartAux(state, &tmp);
 212             return &fState[index];
 213         }
 214
 215         T* WriteNextStateStart(int state, bool* result)
 216         {
 217             UInt32 index = WriteNextStateStartAux(state, result);
 218             return &fState[index];
 219         }
 220
 221         /*!
 222         \brief Stop write operation : make the next state ready to be used by the RT thread
 223         */
 224         void WriteNextStateStop(int state)
 225         {
 226             WriteNextStateStopAux(state);
 227         }
 228
 229 };
 230
 231 } // end of namespace
 232
 233
 234 #endif
 235