1 /* Copyright (c) 2009, 2016, Oracle and/or its affiliates. All rights reserved. 2 3 This program is free software; you can redistribute it and/or modify 4 it under the terms of the GNU General Public License, version 2.0, 5 as published by the Free Software Foundation. 6 7 This program is also distributed with certain software (including 8 but not limited to OpenSSL) that is licensed under separate terms, 9 as designated in a particular file or component or in included license 10 documentation. The authors of MySQL hereby grant you an additional 11 permission to link the program and your derivative works with the 12 separately licensed software that they have included with MySQL. 13 14 This program is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU General Public License, version 2.0, for more details. 18 19 You should have received a copy of the GNU General Public License 20 along with this program; if not, write to the Free Software Foundation, 21 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA */ 22 23 #ifndef PFS_LOCK_H 24 #define PFS_LOCK_H 25 26 /** 27 @file storage/perfschema/pfs_lock.h 28 Performance schema internal locks (declarations). 29 */ 30 31 #include "pfs_atomic.h" 32 33 /** 34 @addtogroup Performance_schema_buffers 35 @{ 36 */ 37 38 /** 39 State of a free record. 40 Values of a free record should not be read by a reader. 41 Writers can concurrently attempt to allocate a free record. 42 */ 43 #define PFS_LOCK_FREE 0x00 44 /** 45 State of a dirty record. 46 Values of a dirty record should not be read by a reader, 47 as the record is currently being modified. 48 Only one writer, the writer which owns the record, should 49 modify the record content. 50 */ 51 #define PFS_LOCK_DIRTY 0x01 52 /** 53 State of an allocated record. 54 Values of an allocated record are safe to read by a reader. 55 A writer may modify some but not all properties of the record: 56 only modifying values that can never cause the reader to crash is allowed. 57 */ 58 #define PFS_LOCK_ALLOCATED 0x02 59 60 #define VERSION_MASK 0xFFFFFFFC 61 #define STATE_MASK 0x00000003 62 #define VERSION_INC 4 63 64 /** 65 A 'lock' protecting performance schema internal buffers. 66 This lock is used to mark the state of a record. 67 Access to the record is not enforced here, 68 it's up to the readers and writers to look at the record state 69 before making an actual read or write operation. 70 */ 71 struct pfs_lock 72 { 73 /** 74 The record internal version and state 75 @sa PFS_LOCK_FREE 76 @sa PFS_LOCK_DIRTY 77 @sa PFS_LOCK_ALLOCATED 78 The version number is to transform the 'ABA' problem 79 (see http://en.wikipedia.org/wiki/ABA_problem) 80 into an 'A(n)BA(n + 1)' problem, where 'n' is the m_version number. 81 When the performance schema instrumentation deletes a record, 82 then create a different record reusing the same memory allocation, 83 the version number is incremented, so that a reader can detect that 84 the record was changed. Note that the version number is never 85 reset to zero when a new record is created. 86 The version number is stored in the high 30 bits. 87 The state is stored in the low 2 bits. 88 */ 89 volatile uint32 m_version_state; 90 91 /** Returns true if the record is free. */ is_freepfs_lock92 bool is_free(void) 93 { 94 uint32 copy= m_version_state; /* non volatile copy, and dirty read */ 95 return ((copy & STATE_MASK) == PFS_LOCK_FREE); 96 } 97 98 /** Returns true if the record contains values that can be read. */ is_populatedpfs_lock99 bool is_populated(void) 100 { 101 uint32 copy= m_version_state; /* non volatile copy, and dirty read */ 102 return ((copy & STATE_MASK) == PFS_LOCK_ALLOCATED); 103 } 104 105 /** 106 Execute a free to dirty transition. 107 This transition is safe to execute concurrently by multiple writers. 108 Only one writer will succeed to acquire the record. 109 @return true if the operation succeed 110 */ free_to_dirtypfs_lock111 bool free_to_dirty(void) 112 { 113 uint32 copy= m_version_state; /* non volatile copy, and dirty read */ 114 uint32 old_val= (copy & VERSION_MASK) + PFS_LOCK_FREE; 115 uint32 new_val= (copy & VERSION_MASK) + PFS_LOCK_DIRTY; 116 117 return (PFS_atomic::cas_u32(&m_version_state, &old_val, new_val)); 118 } 119 120 /** 121 Execute an allocated to dirty transition. 122 This transition should be executed by the writer that owns the record, 123 before the record is modified. 124 */ allocated_to_dirtypfs_lock125 void allocated_to_dirty(void) 126 { 127 uint32 copy= PFS_atomic::load_u32(&m_version_state); 128 /* Make sure the record was ALLOCATED. */ 129 DBUG_ASSERT((copy & STATE_MASK) == PFS_LOCK_ALLOCATED); 130 /* Keep the same version, set the DIRTY state */ 131 uint32 new_val= (copy & VERSION_MASK) + PFS_LOCK_DIRTY; 132 /* We own the record, no need to use compare and swap. */ 133 PFS_atomic::store_u32(&m_version_state, new_val); 134 } 135 136 /** 137 Execute a dirty to allocated transition. 138 This transition should be executed by the writer that owns the record, 139 after the record is in a state ready to be read. 140 */ dirty_to_allocatedpfs_lock141 void dirty_to_allocated(void) 142 { 143 uint32 copy= PFS_atomic::load_u32(&m_version_state); 144 /* Make sure the record was DIRTY. */ 145 DBUG_ASSERT((copy & STATE_MASK) == PFS_LOCK_DIRTY); 146 /* Increment the version, set the ALLOCATED state */ 147 uint32 new_val= (copy & VERSION_MASK) + VERSION_INC + PFS_LOCK_ALLOCATED; 148 PFS_atomic::store_u32(&m_version_state, new_val); 149 } 150 151 /** 152 Initialize a lock to allocated. 153 This transition should be executed by the writer that owns the record and the lock, 154 after the record is in a state ready to be read. 155 */ set_allocatedpfs_lock156 void set_allocated(void) 157 { 158 /* Do not set the version to 0, read the previous value. */ 159 uint32 copy= PFS_atomic::load_u32(&m_version_state); 160 /* Increment the version, set the ALLOCATED state */ 161 uint32 new_val= (copy & VERSION_MASK) + VERSION_INC + PFS_LOCK_ALLOCATED; 162 PFS_atomic::store_u32(&m_version_state, new_val); 163 } 164 165 /** 166 Initialize a lock to dirty. 167 */ set_dirtypfs_lock168 void set_dirty(void) 169 { 170 /* Do not set the version to 0, read the previous value. */ 171 uint32 copy= PFS_atomic::load_u32(&m_version_state); 172 /* Increment the version, set the DIRTY state */ 173 uint32 new_val= (copy & VERSION_MASK) + VERSION_INC + PFS_LOCK_DIRTY; 174 PFS_atomic::store_u32(&m_version_state, new_val); 175 } 176 177 /** 178 Execute a dirty to free transition. 179 This transition should be executed by the writer that owns the record. 180 */ dirty_to_freepfs_lock181 void dirty_to_free(void) 182 { 183 uint32 copy= PFS_atomic::load_u32(&m_version_state); 184 /* Make sure the record was DIRTY. */ 185 DBUG_ASSERT((copy & STATE_MASK) == PFS_LOCK_DIRTY); 186 /* Keep the same version, set the FREE state */ 187 uint32 new_val= (copy & VERSION_MASK) + PFS_LOCK_FREE; 188 PFS_atomic::store_u32(&m_version_state, new_val); 189 } 190 191 /** 192 Execute an allocated to free transition. 193 This transition should be executed by the writer that owns the record. 194 */ allocated_to_freepfs_lock195 void allocated_to_free(void) 196 { 197 /* 198 If this record is not in the ALLOCATED state and the caller is trying 199 to free it, this is a bug: the caller is confused, 200 and potentially damaging data owned by another thread or object. 201 The correct assert to use here to guarantee data integrity is simply: 202 DBUG_ASSERT(m_state == PFS_LOCK_ALLOCATED); 203 */ 204 uint32 copy= PFS_atomic::load_u32(&m_version_state); 205 /* Make sure the record was ALLOCATED. */ 206 DBUG_ASSERT(((copy & STATE_MASK) == PFS_LOCK_ALLOCATED)); 207 /* Keep the same version, set the FREE state */ 208 uint32 new_val= (copy & VERSION_MASK) + PFS_LOCK_FREE; 209 PFS_atomic::store_u32(&m_version_state, new_val); 210 } 211 212 /** 213 Start an optimistic read operation. 214 @sa end_optimist_lock. 215 */ begin_optimistic_lockpfs_lock216 void begin_optimistic_lock(struct pfs_lock *copy) 217 { 218 copy->m_version_state= PFS_atomic::load_u32(&m_version_state); 219 } 220 221 /** 222 End an optimistic read operation. 223 @sa begin_optimist_lock. 224 @return true if the data read is safe to use. 225 */ end_optimistic_lockpfs_lock226 bool end_optimistic_lock(struct pfs_lock *copy) 227 { 228 /* Check there was valid data to look at. */ 229 if ((copy->m_version_state & STATE_MASK) != PFS_LOCK_ALLOCATED) 230 return false; 231 232 /* Check the version + state has not changed. */ 233 if (copy->m_version_state != PFS_atomic::load_u32(&m_version_state)) 234 return false; 235 236 return true; 237 } 238 get_versionpfs_lock239 uint32 get_version() 240 { 241 return (PFS_atomic::load_u32(&m_version_state) & VERSION_MASK); 242 } 243 }; 244 245 246 /** @} */ 247 #endif 248 249