Class RMutex

RMutex

Support

Supported from 5.0

Description

Handle to a mutex. The mutex itself is a Kernel object.

Handles should be closed after use. The base class provides the Close() function which should be called when the handle is no longer required.

Derivation

RHandleBase Handle to an object RMutex Handle to a mutex

Defined in RMutex:
Count(), CreateGlobal(), CreateLocal(), Open(), OpenGlobal(), Signal(), Wait()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

See also:

• RHandleBase::Close()

TInt CreateLocal(TOwnerType aType=EOwnerProcess);

Description

Creates a mutex and opens this handle to that mutex.

The Kernel side object representing the mutex is unnamed. It is, therefore, local to the calling process. The handle can be used directly by any thread within the calling process, but no other RMutex object can open a duplicate handle.

By default, ownership of this mutex handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

TOwnerType aType An enumeration whose enumerators define the ownership of this mutex handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt CreateGlobal(const TDesC& aName,TOwnerType aType=EOwnerProcess);

Description

Creates a mutex that is visible globally and opens this handle to that mutex.

The mutex is visible globally and is assigned the name contained in the specified descriptor. Other threads may open a handle to this mutex.

By default, ownership of this mutex handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aName The name to be assigned to this global mutex. TOwnerType aType An enumeration whose enumerators define the ownership of this mutex handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt OpenGlobal(const TDesC& aName,TOwnerType aType=EOwnerProcess);

Description

Opens a handle onto an existing global mutex which has the same name as that contained in the specified descriptor.

By default, ownership of this mutex handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aName The name of the global mutex which is to be opened. TOwnerType aType An enumeration whose enumerators define the ownership of this mutex handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Open(const TFindMutex& aFind,TOwnerType aType=EOwnerProcess);

Description

Opens a handle onto the global mutex found using a TFindMutex object.

A TFindMutex object is used to find all global mutexes whose full names match a specified pattern.

By default, ownership of this mutex handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TFindMutex& aFind A reference to the object which is used to find the mutex. TOwnerType aType An enumeration whose enumerators define the ownership of this mutex handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• TFindMutex

void Wait();

Description

Waits for access to the mutex.

The function decrements the mutex count by one and returns immediately if it is zero or positive. If the mutex count is negative after being decremented, the calling thread is marked as waiting (on a mutex); the thread is added to the end of a FIFO queue of threads maintained by this mutex.

void Signal();

Description

Signals that the thread is finished with the mutex.

The function increments the mutex count by one. If the count was negative before being incremented, the first thread waiting on the mutex's queue of threads is removed from that queue and, provided that it is not suspended for any other reason, is marked as ready to run. That thread will, therefore, be the next to gain access to the shared resource.

TInt Count();

Description

Returns the current value of the mutex count.

Return value

TInt The current value of the mutex count