1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/euser/us_rwlock.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,426 @@
1.4 +// Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\euser\us_rwlock.cpp
1.18 +//
1.19 +//
1.20 +
1.21 +
1.22 +#include "us_std.h"
1.23 +#include <e32atomics.h>
1.24 +
1.25 +const TInt KReadersIndex = 0;
1.26 +const TInt KWriterIndex = 1;
1.27 +const TInt KReadersPendingIndex = 2;
1.28 +const TInt KWritersPendingIndex = 3;
1.29 +const TUint64 KReaderValue = UI64LIT(0x0000000000000001);
1.30 +const TUint64 KWriterValue = UI64LIT(0x0000000000010000);
1.31 +const TUint64 KReaderPendingValue = UI64LIT(0x0000000100000000);
1.32 +const TUint64 KWriterPendingValue = UI64LIT(0x0001000000000000);
1.33 +const TUint64 KReadersMask = UI64LIT(0x000000000000ffff);
1.34 +const TUint64 KWriterMask = KWriterValue;
1.35 +const TUint64 KReadersOrWritersMask = KReadersMask | KWriterMask;
1.36 +const TUint64 KReadersPendingClearMask = UI64LIT(0xffff0000ffffffff);
1.37 +
1.38 +/**
1.39 +Initialise a read-write lock object.
1.40 +@param aPriority Type of priority to use - see RReadWriteLockPriority::TReadWriteLockPriority
1.41 +@return KErrNone Instance successfully created
1.42 + Otherwise an error returned by RSemaphore::CreateLocal
1.43 +@panic EReadWriteLockInvalidPriority if aPriority is not valid.
1.44 +*/
1.45 +EXPORT_C TInt RReadWriteLock::CreateLocal(TReadWriteLockPriority aPriority)
1.46 + {
1.47 + __ASSERT_ALWAYS(aPriority >= EWriterPriority && aPriority <= EReaderPriority, Panic(EReadWriteLockInvalidPriority));
1.48 +
1.49 + iPriority = aPriority;
1.50 + iValues = 0;
1.51 +#ifdef _DEBUG
1.52 + iSpare[0] = 0; // Keep a rough track of writer starvation
1.53 +#endif
1.54 +
1.55 + TInt ret = iReaderSem.CreateLocal(0, EOwnerProcess);
1.56 + if (ret == KErrNone)
1.57 + ret = iWriterSem.CreateLocal(0, EOwnerProcess);
1.58 + if (ret != KErrNone)
1.59 + iReaderSem.Close();
1.60 +
1.61 + return ret;
1.62 + }
1.63 +
1.64 +/**
1.65 +Close a read-write lock object, releasing the associated semaphores.
1.66 +@panic EReadWriteLockStillPending if there are any outstanding clients or pending clients
1.67 +*/
1.68 +EXPORT_C void RReadWriteLock::Close()
1.69 + {
1.70 + __ASSERT_ALWAYS(iValues == 0, Panic(EReadWriteLockStillPending));
1.71 +
1.72 + iReaderSem.Close();
1.73 + iWriterSem.Close();
1.74 + }
1.75 +
1.76 +/**
1.77 +Ask for a read lock. Will be granted if:
1.78 + 1) No-one else currently holds the lock or
1.79 + 2) Only readers hold the lock and:
1.80 + a) There are no pending writers or
1.81 + b) The priority is for readers.
1.82 +Otherwise this function blocks until the lock becomes available to it.
1.83 +Please note that ReadLock() is not re-entrant - calling it a second time without releasing the first lock
1.84 +runs the risk of being blocked and risking a deadlock situation.
1.85 +@panic EReadWriteLockTooManyClients if the resulting number of readers or pending readers exceeds EReadWriteLockClientCategoryLimit
1.86 +*/
1.87 +EXPORT_C void RReadWriteLock::ReadLock()
1.88 + {
1.89 + TBool blocked;
1.90 + TUint64 initialValues;
1.91 + TUint16* indexedValues = (TUint16*)&initialValues;
1.92 +
1.93 + do {
1.94 + initialValues = iValues;
1.95 +
1.96 + if (indexedValues[KWriterIndex] > 0 ||
1.97 + (iPriority != EReaderPriority && indexedValues[KWritersPendingIndex] > 0))
1.98 + {
1.99 + __ASSERT_ALWAYS(indexedValues[KReadersPendingIndex] < KMaxTUint16, Panic(EReadWriteLockTooManyClients));
1.100 + blocked = ETrue;
1.101 + }
1.102 + else
1.103 + {
1.104 + __ASSERT_ALWAYS(indexedValues[KReadersIndex] < KMaxTUint16, Panic(EReadWriteLockTooManyClients));
1.105 + blocked = EFalse;
1.106 + }
1.107 + }
1.108 + while (!__e32_atomic_cas_rel64(&iValues, &initialValues, initialValues + (blocked ? KReaderPendingValue : KReaderValue)));
1.109 +
1.110 + if (blocked)
1.111 + iReaderSem.Wait();
1.112 + }
1.113 +
1.114 +/**
1.115 +Ask for a write lock. Will be granted if no-one else currently holds the lock.
1.116 +Otherwise this function blocks until the lock becomes available to it.
1.117 +Only one writer can hold the lock at one time. No readers can hold the lock while a writer has it.
1.118 +Please note that WriteLock() is not re-entrant - calling it a second time without releasing the first lock
1.119 +will block and cause a deadlock situation.
1.120 +@panic EReadWriteLockTooManyClients if the resulting number of pending writers exceeds EReadWriteLockClientCategoryLimit
1.121 +*/
1.122 +EXPORT_C void RReadWriteLock::WriteLock()
1.123 + {
1.124 + TBool blocked;
1.125 + TUint64 initialValues;
1.126 + TUint16* indexedValues = (TUint16*)&initialValues;
1.127 +
1.128 + do {
1.129 + initialValues = iValues;
1.130 +
1.131 + if (initialValues & KReadersOrWritersMask)
1.132 + {
1.133 + __ASSERT_ALWAYS(indexedValues[KWritersPendingIndex] < KMaxTUint16, Panic(EReadWriteLockTooManyClients));
1.134 + blocked = ETrue;
1.135 + }
1.136 + else
1.137 + {
1.138 + blocked = EFalse;
1.139 + }
1.140 + }
1.141 + while (!__e32_atomic_cas_rel64(&iValues, &initialValues, initialValues + (blocked ? KWriterPendingValue : KWriterValue)));
1.142 +
1.143 + if (blocked)
1.144 + iWriterSem.Wait();
1.145 + }
1.146 +
1.147 +/**
1.148 +Ask for a read lock without blocking.
1.149 +@return ETrue - lock granted
1.150 + EFalse - failed to obtain the lock
1.151 +@panic EReadWriteLockTooManyClients if the resulting number of readers exceeds EReadWriteLockClientCategoryLimit
1.152 +@see ReadLock()
1.153 +*/
1.154 +EXPORT_C TBool RReadWriteLock::TryReadLock()
1.155 + {
1.156 + TUint64 initialValues;
1.157 + TUint16* indexedValues = (TUint16*)&initialValues;
1.158 +
1.159 + do {
1.160 + initialValues = iValues;
1.161 +
1.162 + if (indexedValues[KWriterIndex] > 0 ||
1.163 + (iPriority != EReaderPriority && indexedValues[KWritersPendingIndex] > 0))
1.164 + return EFalse;
1.165 +
1.166 + __ASSERT_ALWAYS(indexedValues[KReadersIndex] < KMaxTUint16, Panic(EReadWriteLockTooManyClients));
1.167 + }
1.168 + while (!__e32_atomic_cas_rel64(&iValues, &initialValues, initialValues + KReaderValue));
1.169 +
1.170 + return ETrue;
1.171 + }
1.172 +
1.173 +/**
1.174 +Ask for a write lock without blocking.
1.175 +@return ETrue - lock granted
1.176 + EFalse - failed to obtain the lock
1.177 +@see WriteLock()
1.178 +*/
1.179 +EXPORT_C TBool RReadWriteLock::TryWriteLock()
1.180 + {
1.181 + TUint64 initialValues;
1.182 +
1.183 + do {
1.184 + initialValues = iValues;
1.185 +
1.186 + if (initialValues & KReadersOrWritersMask)
1.187 + return EFalse;
1.188 + }
1.189 + while (!__e32_atomic_cas_rel64(&iValues, &initialValues, initialValues + KWriterValue));
1.190 +
1.191 + return ETrue;
1.192 + }
1.193 +
1.194 +/**
1.195 +Tries to atomically release a read lock and gain a write lock.
1.196 +This function will succeed if:
1.197 + - This is the only reader and
1.198 + - There are no pending writers or
1.199 + - The priority is reader
1.200 +@return ETrue - write lock granted
1.201 + EFalse - failed to obtain a write lock, read lock retained
1.202 +@panic EReadWriteLockBadLockState if the read lock is not currently held
1.203 +*/
1.204 +EXPORT_C TBool RReadWriteLock::TryUpgradeReadLock()
1.205 + {
1.206 + __ASSERT_ALWAYS((iValues & KReadersMask) != 0, Panic(EReadWriteLockBadLockState)); // Check we actually hold a read lock
1.207 + __ASSERT_DEBUG((iValues & KWriterMask) == 0, Panic(EReadWriteLockBadLockState)); // Check we don't hold a write lock - shouldn't be possible
1.208 +
1.209 + TUint64 initialValues;
1.210 + TUint16* indexedValues = (TUint16*)&initialValues;
1.211 +
1.212 + do {
1.213 + initialValues = iValues;
1.214 +
1.215 + if (indexedValues[KReadersIndex] > 1 ||
1.216 + (iPriority != EReaderPriority && indexedValues[KWritersPendingIndex] > 0))
1.217 + return EFalse;
1.218 + }
1.219 + while (!__e32_atomic_cas_acq64(&iValues, &initialValues, initialValues - KReaderValue + KWriterValue));
1.220 +
1.221 + return ETrue;
1.222 + }
1.223 +
1.224 +/**
1.225 +Atomically releases a held write lock and gains a read lock. Also unblocks any
1.226 +pending readers if:
1.227 + - Priority is EPriorityReader or
1.228 + - There are no pending writers
1.229 +This function can not fail, so it does not return anything.
1.230 +@panic EReadWriteLockBadLockState if the lock is not currently held
1.231 +*/
1.232 +EXPORT_C void RReadWriteLock::DowngradeWriteLock()
1.233 + {
1.234 + __ASSERT_ALWAYS((iValues & KWriterMask) == KWriterValue, Panic(EReadWriteLockBadLockState)); // Check we actually hold a write lock
1.235 + __ASSERT_DEBUG((iValues & KReadersMask) == 0, Panic(EReadWriteLockBadLockState)); // Check we don't hold a read lock - shouldn't be possible
1.236 +
1.237 + TUint unlockReaders;
1.238 + TUint64 initialValues;
1.239 + TUint16* indexedValues = (TUint16*)&initialValues;
1.240 + TUint64 newValues;
1.241 +
1.242 + do {
1.243 + unlockReaders = 0;
1.244 + initialValues = iValues;
1.245 + newValues = initialValues - KWriterValue + KReaderValue; // Clear current write lock flag and add a read lock
1.246 +
1.247 + if (indexedValues[KReadersPendingIndex] > 0 &&
1.248 + (indexedValues[KWritersPendingIndex] == 0 || iPriority == EReaderPriority)) // Release any other pending readers
1.249 + {
1.250 + unlockReaders = indexedValues[KReadersPendingIndex];
1.251 + newValues &= KReadersPendingClearMask; // Clear pending readers
1.252 +
1.253 + if (unlockReaders == KMaxTUint16) // Put a pending reader back to avoid overflow in the readers field
1.254 + {
1.255 + unlockReaders--;
1.256 + newValues += KReaderPendingValue;
1.257 + }
1.258 +
1.259 + newValues += unlockReaders;
1.260 + }
1.261 + }
1.262 + while (!__e32_atomic_cas_acq64(&iValues, &initialValues, newValues));
1.263 +
1.264 + if (unlockReaders > 0)
1.265 + iReaderSem.Signal(unlockReaders);
1.266 + }
1.267 +
1.268 +/**
1.269 +Releases a held read or write lock. If no-one else holds this lock (ie other
1.270 +readers) then this will unblock one or more pending clients based on the priority:
1.271 + EAlternatePriority - If a read lock is being released then:
1.272 + - Give the lock to the first pending writer, if there is one
1.273 + - Else give the lock to all pending readers, if there are any
1.274 + - If a write lock is being released then:
1.275 + - If there are pending readers:
1.276 + - If there are pending writers then unblock one pending reader
1.277 + - Else if there are no pending writers then unblock all pending readers
1.278 + - Else unblock one pending writer, if there is one
1.279 + EReaderPriority - Unblock all pending readers. If none then unblock one pending writer, if there is one
1.280 + EWriterPriority - Unblock one pending writer, if there is one. If none then unblock any and all pending readers
1.281 +@panic EReadWriteLockBadLockState if the lock is not currently held
1.282 +*/
1.283 +EXPORT_C void RReadWriteLock::Unlock()
1.284 + {
1.285 + __ASSERT_ALWAYS((iValues & KReadersOrWritersMask) != 0, Panic(EReadWriteLockBadLockState)); // Check we actually hold a lock
1.286 + __ASSERT_DEBUG((iValues & KReadersOrWritersMask) <= KWriterValue, Panic(EReadWriteLockBadLockState)); // Check we don't hold a read lock and a write lock at the same time - shouldn't be possible
1.287 +
1.288 + TInt unlockClients = 0;
1.289 +
1.290 + switch (iPriority)
1.291 + {
1.292 + case EWriterPriority:
1.293 + unlockClients = UnlockWriter(); break;
1.294 + case EAlternatePriority:
1.295 + unlockClients = UnlockAlternate(); break;
1.296 + default: // EReaderPriority:
1.297 + unlockClients = UnlockReader(); break;
1.298 + };
1.299 +
1.300 + if (unlockClients == -1)
1.301 + {
1.302 +#ifdef _DEBUG
1.303 + iSpare[0] = 0; // Keep a rough track of writer starvation
1.304 +#endif
1.305 + iWriterSem.Signal();
1.306 + }
1.307 + else if (unlockClients > 0)
1.308 + {
1.309 +#ifdef _DEBUG
1.310 + const TUint64 KWritersPendingMask = UI64LIT(0xffff000000000000);
1.311 + if (iValues & KWritersPendingMask)
1.312 + iSpare[0]++; // Keep a rough track of writer starvation
1.313 + if (iSpare[0] > 1000)
1.314 + Panic(EReadWriteLockWriterStarvation);
1.315 +#endif
1.316 + iReaderSem.Signal(unlockClients);
1.317 + }
1.318 + }
1.319 +
1.320 +TInt RReadWriteLock::UnlockWriter()
1.321 + {
1.322 + TUint64 initialValues;
1.323 + TUint16* indexedValues = (TUint16*)&initialValues;
1.324 + TUint64 newValues;
1.325 + TInt unlockClients;
1.326 +
1.327 + do {
1.328 + unlockClients = 0;
1.329 + initialValues = iValues;
1.330 + newValues = initialValues - (indexedValues[KReadersIndex] > 0 ? KReaderValue : KWriterValue); // Clear current lock flag
1.331 +
1.332 + if ((newValues & KReadersOrWritersMask) == 0) // No longer locked - release someone else
1.333 + {
1.334 + if (indexedValues[KWritersPendingIndex] > 0) // Release a writer
1.335 + {
1.336 + unlockClients = -1;
1.337 + newValues -= KWriterPendingValue;
1.338 + newValues += KWriterValue;
1.339 + }
1.340 + else if (indexedValues[KReadersPendingIndex] > 0) // Release all pending readers
1.341 + {
1.342 + unlockClients = indexedValues[KReadersPendingIndex];
1.343 + newValues &= KReadersPendingClearMask; // Clear pending readers
1.344 + newValues += unlockClients;
1.345 + }
1.346 + }
1.347 + }
1.348 + while (!__e32_atomic_cas_acq64(&iValues, &initialValues, newValues));
1.349 +
1.350 + return unlockClients;
1.351 + }
1.352 +
1.353 +TInt RReadWriteLock::UnlockAlternate()
1.354 + {
1.355 + TUint64 initialValues;
1.356 + TUint16* indexedValues = (TUint16*)&initialValues;
1.357 + TUint64 newValues;
1.358 + TInt unlockClients;
1.359 +
1.360 + do {
1.361 + unlockClients = 0;
1.362 + initialValues = iValues;
1.363 + newValues = initialValues - (indexedValues[KReadersIndex] > 0 ? KReaderValue : KWriterValue); // Clear current lock flag
1.364 +
1.365 + if ((newValues & KReadersOrWritersMask) == 0) // No longer locked - release someone else
1.366 + {
1.367 + if (indexedValues[KWritersPendingIndex] > 0 &&
1.368 + (indexedValues[KReadersIndex] > 0 || indexedValues[KReadersPendingIndex] == 0)) // Release a writer if there is one and either this is a read unlock or there are no readers pending
1.369 + {
1.370 + unlockClients = -1;
1.371 + newValues -= KWriterPendingValue;
1.372 + newValues += KWriterValue;
1.373 + }
1.374 + else if (indexedValues[KReadersPendingIndex] > 0) // Release one or more readers
1.375 + {
1.376 + if (indexedValues[KWritersPendingIndex] > 0) // Just one because there are pending writers
1.377 + {
1.378 + unlockClients = 1;
1.379 + newValues -= KReaderPendingValue;
1.380 + newValues += KReaderValue;
1.381 + }
1.382 + else // All of them
1.383 + {
1.384 + unlockClients = indexedValues[KReadersPendingIndex];
1.385 + newValues &= KReadersPendingClearMask; // Clear pending readers
1.386 + newValues += unlockClients;
1.387 + }
1.388 + }
1.389 +
1.390 + }
1.391 + }
1.392 + while (!__e32_atomic_cas_acq64(&iValues, &initialValues, newValues));
1.393 +
1.394 + return unlockClients;
1.395 + }
1.396 +
1.397 +TInt RReadWriteLock::UnlockReader()
1.398 + {
1.399 + TUint64 initialValues;
1.400 + TUint16* indexedValues = (TUint16*)&initialValues;
1.401 + TUint64 newValues;
1.402 + TInt unlockClients;
1.403 +
1.404 + do {
1.405 + unlockClients = 0;
1.406 + initialValues = iValues;
1.407 + newValues = initialValues - (indexedValues[KReadersIndex] > 0 ? KReaderValue : KWriterValue); // Clear current lock flag
1.408 +
1.409 + if ((newValues & KReadersOrWritersMask) == 0) // No longer locked - release someone else
1.410 + {
1.411 + if (indexedValues[KReadersPendingIndex] > 0) // Release all pending readers
1.412 + {
1.413 + unlockClients = indexedValues[KReadersPendingIndex];
1.414 + newValues &= KReadersPendingClearMask; // Clear pending readers
1.415 + newValues += unlockClients;
1.416 + }
1.417 + else if (indexedValues[KWritersPendingIndex] > 0) // Release a writer
1.418 + {
1.419 + unlockClients = -1;
1.420 + newValues -= KWriterPendingValue;
1.421 + newValues += KWriterValue;
1.422 + }
1.423 + }
1.424 + }
1.425 + while (!__e32_atomic_cas_acq64(&iValues, &initialValues, newValues));
1.426 +
1.427 + return unlockClients;
1.428 + }
1.429 +