WpRequestObjectMutexSem

This method is specific to Version 4, or higher, of the OS/2 operating system.

Each object has associated with it a mutex semaphore that can be used to serialize access to resources. This instance method is called to request the mutex semaphore for an object.

Syntax

_wpRequestObjectMutexSem(somSelf, ulTimeout)

Parameters

somSelf (WPObject *) - input

Pointer to the object on which the method is being invoked.

Points to an object of class WPObject.

ulTimeout (ULONG) - input

Return code from WinRequestMutexSem.

Returns

rc (ULONG) - returns

Success indicator.

TRUE: The object semaphore is held by the calling thread.

FALSE: The object semaphore is not held by the calling thread.

Remarks

The Workplace Shell calls the wpRequestObjectMutexSem method to stop other threads from modifying an object while it is updating it. For example, when the Workplace Shell is enumerating the objects within a folder, it calls the wpRequestObjectMutexSem method for the folder to stop new objects from being added to the folder or old objects from being removed from the folder.

Each object has associated with it a mutex semaphore that can be used to serialize access to resources. This method is called to assert that the current thread indeed holds this mutex semaphore. Methods that expect to be invoked under semaphore protection can use this method to validate that the caller has indeed obtained ownership of the mutex semaphore.

This semaphore is used primarily to control access to the linked list of use items, but can be used for other purposes if needed. Folders also have a separate mutex semaphore, which is used to protect the content chain for that folder.

If you need both the object and the folder mutex semaphores, then you must obtain the folder mutex first.

If you need multiple object mutex semaphores, obtain them in object address order.

As with most semaphores, hold the semaphore for the minimum possible time.

Usage

You can call the wpRequestObjectMutexSem method at any time to serialize access to an object.

How to Override

This method is not generally overridden.

Example Code

In this example, you lock the folder pointed to by somSelf and enumerate all objects within the folder. When you are finished processing the objects in the folder, you unlock the folder.

WPObject *Object;
BOOL     bSem;

bSem = !_wpRequestObjectMutexSem(somSelf,SEM_INDEFINITE_WAIT);
for (Object = _wpQueryContent(somSelf,NULL,QC_FIRST);
     Object;
     Object = _wpQueryContent(somSelf,Object,QC_NEXT));
{
   /***** Process the returned object *****/
}

if (bSem)
{
   _wpReleaseObjectMutexSem(somSelf);
}

Related Methods

• wpAssertObjectMutexSem
• wpReleaseObjectMutexSem