Collapse all Symbian^3 Application Developer Library

RReadWriteLock Class Reference

class RReadWriteLock

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 .

Public Member Functions
	RReadWriteLock ()
IMPORT_C void	Close ()
IMPORT_C TInt	CreateLocal ( TReadWriteLockPriority )
IMPORT_C void	DowngradeWriteLock ()
IMPORT_C void	ReadLock ()
IMPORT_C TBool	TryReadLock ()
IMPORT_C TBool	TryUpgradeReadLock ()
IMPORT_C TBool	TryWriteLock ()
IMPORT_C void	Unlock ()
IMPORT_C void	WriteLock ()

Private Member Functions
	RReadWriteLock (const RReadWriteLock &)
TInt	UnlockAlternate ()
TInt	UnlockReader ()
TInt	UnlockWriter ()
RReadWriteLock &	operator= (const RReadWriteLock &)

Public Member Enumerations
enum	TReadWriteLockClientCategoryLimit { EReadWriteLockClientCategoryLimit = KMaxTUint16 }
enum	TReadWriteLockPriority { EWriterPriority , EAlternatePriority , EReaderPriority }

Private Attributes
TReadWriteLockPriority	iPriority
RSemaphore	iReaderSem
TUint32	iSpare
TUint64	iValues
RSemaphore	iWriterSem

Constructor & Destructor Documentation

RReadWriteLock()

RReadWriteLock

(

)

[inline]

Default constructor.

RReadWriteLock(const RReadWriteLock &)

RReadWriteLock

(

const RReadWriteLock &

aLock

)

[private]

Parameters

const RReadWriteLock & aLock

Member Functions Documentation

Close()

IMPORT_C void

(

)

Close a read-write lock object, releasing the associated semaphores.

panic: EReadWriteLockStillPending if there are any outstanding clients or pending clients

CreateLocal(TReadWriteLockPriority)

IMPORT_C TInt

CreateLocal

(

TReadWriteLockPriority

aPriority = EWriterPriority

)

Initialise a read-write lock object.

panic: EReadWriteLockInvalidPriority if aPriority is not valid.

Parameters

TReadWriteLockPriority aPriority = EWriterPriority

Type of priority to use - see RReadWriteLockPriority::TReadWriteLockPriority

DowngradeWriteLock()

IMPORT_C void

DowngradeWriteLock

(

)

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

EReadWriteLockBadLockState if the lock is not currently held

ReadLock()

IMPORT_C void

ReadLock

(

)

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: EReadWriteLockTooManyClients if the resulting number of readers or pending readers exceeds EReadWriteLockClientCategoryLimit

TryReadLock()

IMPORT_C TBool

TryReadLock

(

)

Ask for a read lock without blocking.

panic: EReadWriteLockTooManyClients if the resulting number of readers exceeds EReadWriteLockClientCategoryLimit

ReadLock()

TryUpgradeReadLock()

IMPORT_C TBool

TryUpgradeReadLock

(

)

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
  
  panic
  
  EReadWriteLockBadLockState if the read lock is not currently held

TryWriteLock()

IMPORT_C TBool

TryWriteLock

(

)

Ask for a write lock without blocking. WriteLock()

Unlock()

IMPORT_C void

Unlock

(

)

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

EReadWriteLockBadLockState if the lock is not currently held

UnlockAlternate()

TInt

UnlockAlternate

(

)

[private]

UnlockReader()

TInt

UnlockReader

(

)

[private]

UnlockWriter()

TInt

UnlockWriter

(

)

[private]

WriteLock()

IMPORT_C void

WriteLock

(

)

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: EReadWriteLockTooManyClients if the resulting number of pending writers exceeds EReadWriteLockClientCategoryLimit

operator=(const RReadWriteLock &)

RReadWriteLock &

operator=

(

const RReadWriteLock &

aLock

)

[private]

Parameters

const RReadWriteLock & aLock

Member Enumerations Documentation

Enum TReadWriteLockClientCategoryLimit

Enumerators

EReadWriteLockClientCategoryLimit = KMaxTUint16

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

Enum TReadWriteLockPriority

Enumerators

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!