Class RMutex

class RMutex : public RHandleBase;

Description

A handle to a mutex.

The mutex itself is a kernel side object.

Handles should be closed after use. RHandleBase provides the necessary RHandleBase::Close() function which should be called when the handle is no longer required.

Derivation

• RHandleBase - A handle to an object.

• RMutex - A handle to a mutex.

Members

Defined in RMutex:

• CreateGlobal(const TDesC &,TOwnerType)Creates a global mutex and opens this handle to the mutex.
• CreateLocal(TOwnerType)Creates a mutex and opens this handle to the mutex.
• IsHeld()Test if this mutex is held by the current thread.
• Open(RMessagePtr2,TInt,TOwnerType)Opens a handle to a mutex using a handle number sent by a client to a server.
• Open(TInt,TOwnerType)Opens a handle to a mutex using a handle number passed as an environment data it...
• Open(const TFindMutex &,TOwnerType)Opens a handle to the global mutex found using a TFindMutex object.
• OpenGlobal(const TDesC &,TOwnerType)Opens a handle to a global mutex.
• Signal()Release the mutex.
• Wait()Acquire the mutex, waiting for it to become free if necessary.

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

See also:

• RHandleBase::Close()Closes the handle.

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

Description

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

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

By default, any thread in the process can use this instance of RMutex to access the mutex. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RMutex to access the mutex; any other thread in this process that wants to access the mutex must either duplicate the handle or use RMutex::OpenGlobal(const TDesC &,TOwnerType) again.

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 one of the other system wide error codes.

IMPORT_C TInt CreateLocal(TOwnerType aType=EOwnerProcess);

Description

Creates a mutex and opens this handle to the mutex.

The kernel side object representing the mutex is unnamed. This means that it is not possible to search for the mutex, which makes it local to the current process.

By default, any thread in the process can use this instance of RMutex to access the mutex. However, specifying EOwnerThread as the parameter to this function, means that only the creating thread can use this instance of RMutex to access the mutex; any other thread in this process that wants to access the mutex must duplicate this handle.

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 one of the system wide error codes.

See also:

• RHandleBase::Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...

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

Description

Creates a global mutex and opens this handle to the mutex.

The kernel side object representing the mutex is given the name contained in the specified descriptor, which makes it global. This means that any thread in any process can search for the mutex, using TFindMutex, and open a handle to it. If the specified name is empty the kernel side object representing the mutex is unnamed and so cannot be opened by name. It can however be passed to another process as a process parameter or via IPC.

By default, any thread in the process can use this instance of RMutex to access the mutex. However, specifying EOwnerThread as the second parameter to this function, means that only the creating thread can use this instance of RMutex to access the mutex; any other thread in this process that wants to access the mutex must either duplicate this handle or use RMutex::OpenGlobal(const TDesC &,TOwnerType).

Parameters

const TDesC16 &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 one of the other system wide error codes.

See also:

• RMutex::OpenGlobal(const TDesC &,TOwnerType)Opens a handle to a global mutex.
• RHandleBase::Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...

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

Description

Opens a handle to a global mutex.

Global mutexes are identified by name.

By default, any thread in the process can use this instance of RMutex to access the mutex. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RMutex to access the mutex; any other thread in this process that wants to access the mutex must either duplicate the handle or use RMutex::OpenGlobal(const TDesC &,TOwnerType) again.

Parameters

const TDesC16 &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.

See also:

• RHandleBase::Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...

IMPORT_C TInt Open(RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a mutex using a handle number sent by a client to a server.

This function is called by the server.

Parameters

RMessagePtr2 aMessage The message pointer. TInt aParam An index specifying which of the four message arguments contains the handle number. 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; KErrArgument, if the value of aParam is outside the range 0-3; KErrBadHandle, if not a valid handle; otherwise one of the other system-wide error codes.

IMPORT_C TInt Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a mutex using a handle number passed as an environment data item to the child process during the creation of that child process.

Note that this function can only be called successfully once.

Parameters

TInt aArgumentIndex An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15. 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; KErrNotFound, if the slot indicated by aArgumentIndex is empty; KErrArgument, if the slot does not contain a mutex handle; otherwise one of the other system-wide error codes.

See also:

• RProcess::SetParameter(TInt,RHandleBase)Sets the specified handle into the specified environment data slot for this proc...

IMPORT_C void Wait();

Description

Acquire the mutex, waiting for it to become free if necessary.

This function checks if the mutex is currently held. If not the mutex is marked as held by the current thread and the call returns immediately. If the mutex is held by another thread the current thread will suspend until the mutex becomes free. If the mutex is already held by the current thread a count is maintained of how many times the thread has acquired the mutex.

IMPORT_C void Signal();

Pre-Condition

The mutex must previously have been acquired by the current thread calling RMutex::Wait().

Description

Release the mutex.

This function decrements the count of how many times the current thread has acquired this mutex. If the count is now zero the mutex is marked as free and, if any other threads are waiting for the mutex to become free, the highest priority among those is made ready to run. However the mutex is not marked as held by any thread - the thread which has just been awakened must actually run in order to acquire the mutex.

Panic codes

KERN-EXEC 1 If the mutex has not previously been acquired by the current thread calling Wait().

IMPORT_C TBool IsHeld();

Description

Test if this mutex is held by the current thread.

Return value

TBool True if the current thread has waited on the mutex, false otherwise.