RReadWriteLock Class Reference

#include <e32cmn.h>

class RReadWriteLock
Public Member Enumerations
enumTReadWriteLockClientCategoryLimit { EReadWriteLockClientCategoryLimit }
enumTReadWriteLockPriority { EWriterPriority, EAlternatePriority, EReaderPriority }
Public Member Functions
RReadWriteLock()
IMPORT_C voidClose()
IMPORT_C TIntCreateLocal(TReadWriteLockPriority)
IMPORT_C voidDowngradeWriteLock()
IMPORT_C voidReadLock()
IMPORT_C TBoolTryReadLock()
IMPORT_C TBoolTryUpgradeReadLock()
IMPORT_C TBoolTryWriteLock()
IMPORT_C voidUnlock()
IMPORT_C voidWriteLock()

Detailed Description

A read-write lock.

This is a lock for co-ordinating readers and writers to shared resources. It is designed to allow multiple concurrent readers. It is not a kernel side object and so does not inherit from RHandleBase.

Member Enumeration Documentation

Enum TReadWriteLockClientCategoryLimit

EnumeratorValueDescription
EReadWriteLockClientCategoryLimitKMaxTUint16

Maximum number of clients in each category: read locked, read lock pending, write lock pending

Enum TReadWriteLockPriority

EnumeratorValueDescription
EWriterPriority

Pending writers always get the lock before pending readers

EAlternatePriority

Lock is given alternately to pending readers and writers

EReaderPriority

Pending readers always get the lock before pending writers - beware writer starvation!

Constructor & Destructor Documentation

RReadWriteLock ( )

RReadWriteLock()[inline]

Default constructor.

Member Function Documentation

Close ( )

IMPORT_C voidClose()
Close a read-write lock object, releasing the associated semaphores.
Panic Codes
EReadWriteLockStillPendingif there are any outstanding clients or pending clients

CreateLocal ( TReadWriteLockPriority )

IMPORT_C TIntCreateLocal(TReadWriteLockPriorityaPriority = EWriterPriority)
Initialise a read-write lock object.
Parameters
aPriorityType of priority to use - see RReadWriteLockPriority::TReadWriteLockPriority
Return Value
KErrNone Instance successfully created Otherwise an error returned by RSemaphore::CreateLocal
Panic Codes
EReadWriteLockInvalidPriorityif aPriority is not valid.

DowngradeWriteLock ( )

IMPORT_C voidDowngradeWriteLock()
Atomically releases a held write lock and gains a read lock. Also unblocks any pending readers if:

  • Priority is EPriorityReader or

  • There are no pending writers This function can not fail, so it does not return anything.
Panic Codes
EReadWriteLockBadLockStateif the lock is not currently held

ReadLock ( )

IMPORT_C voidReadLock()
Ask for a read lock. Will be granted if: 1) No-one else currently holds the lock or 2) Only readers hold the lock and: a) There are no pending writers or b) The priority is for readers. Otherwise this function blocks until the lock becomes available to it. Please note that ReadLock() is not re-entrant - calling it a second time without releasing the first lock runs the risk of being blocked and risking a deadlock situation.
Panic Codes
EReadWriteLockTooManyClientsif the resulting number of readers or pending readers exceeds EReadWriteLockClientCategoryLimit

TryReadLock ( )

IMPORT_C TBoolTryReadLock()
Ask for a read lock without blocking.

See also: ReadLock()

Return Value
ETrue - lock granted EFalse - failed to obtain the lock
Panic Codes
EReadWriteLockTooManyClientsif the resulting number of readers exceeds EReadWriteLockClientCategoryLimit

TryUpgradeReadLock ( )

IMPORT_C TBoolTryUpgradeReadLock()
Tries to atomically release a read lock and gain a write lock. This function will succeed if:
  • This is the only reader and

    • There are no pending writers or

    • The priority is reader
Return Value
ETrue - write lock granted EFalse - failed to obtain a write lock, read lock retained
Panic Codes
EReadWriteLockBadLockStateif the read lock is not currently held

TryWriteLock ( )

IMPORT_C TBoolTryWriteLock()

Ask for a write lock without blocking.

See also: WriteLock()

Return Value
ETrue - lock granted EFalse - failed to obtain the lock

Unlock ( )

IMPORT_C voidUnlock()
Releases a held read or write lock. If no-one else holds this lock (ie other readers) then this will unblock one or more pending clients based on the priority: EAlternatePriority - If a read lock is being released then:

  • Give the lock to the first pending writer, if there is one

  • Else give the lock to all pending readers, if there are any

If a write lock is being released then:
  • If there are pending readers:

    • If there are pending writers then unblock one pending reader

    • Else if there are no pending writers then unblock all pending readers

  • Else unblock one pending writer, if there is one EReaderPriority - Unblock all pending readers. If none then unblock one pending writer, if there is one EWriterPriority - Unblock one pending writer, if there is one. If none then unblock any and all pending readers
Panic Codes
EReadWriteLockBadLockStateif the lock is not currently held

WriteLock ( )

IMPORT_C voidWriteLock()
Ask for a write lock. Will be granted if no-one else currently holds the lock. Otherwise this function blocks until the lock becomes available to it. Only one writer can hold the lock at one time. No readers can hold the lock while a writer has it. Please note that WriteLock() is not re-entrant - calling it a second time without releasing the first lock will block and cause a deadlock situation.
Panic Codes
EReadWriteLockTooManyClientsif the resulting number of pending writers exceeds EReadWriteLockClientCategoryLimit
© Nokia 2005.