ISharedResource

The ISharedResource class defines a resource that can be shared across multiple processes. Use the name you provide on construction to distinguish between shared resources.

Portability Considerations

Use a keyName value that is a valid file name in all of the target environments.

AIX Considerations

You might use ISharedResource objects to serialize resource access with applications that were not written using the Open Class Library. To make this work correctly, your non-Open Class Library application needs to use the AIX semaphore object in a manner consistent with the Open Class Library. To help you understand how the semaphore object is used by the Open Class Library, the basic interaction with the system's subroutines is described below.

The AIX semop subroutine is used for the semaphore lock and release operations. The ISharedResource constructor uses the semget subroutine to allocate a set containing two semaphores. The first semaphore in this set represents the state of the lock. The constructor initializes the semval field to free (value of 0). A lock operation increments the value, while an unlock operation decrements the value.

Recursive lock operations by the same process are allowed. In this case, the resource remains owned by the process until an equal number of unlock operations are done or the object is deleted. The second semaphore in the set is used as a reference counter to indicate the number of ISharedResource objects that are referencing this semaphore set. The constructor increments this counter and the destructor decrements it. When the counter reaches 0, the destructor calls the semctl subroutine to delete the semaphore set.

The constructor determines the semaphore identifier to use in the semget subroutine by using the ftok system subroutine. If the parameter provided on the constructor begins with a slash (/) or is an existing file, the parameter is used as a file name for the ftok call and is the basis of the semaphore identifier token. If the parameter is not the name of an existing file, the constructor interprets the string as the name of a file in the /tmp directory. If this file does not exist, it is created. You can use keyName to obtain the file name used on the ftok subroutine call. The constructor always uses a value of 1 for the second parameter of ftok.


ISharedResource - Member Functions and Data by Group

Constructors & Destructor

Use these members to construct and destruct objects of this class.


[view class]
~ISharedResource
public:
virtual ~ISharedResource()
Destroys a shared resource object.

Exception

IAccessError The shared resource object was not deleted. The semaphore handle may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ISharedResource
public:
ISharedResource(const char* keyName)
Construct a shared resource. You can only construct objects of this class by providing a name that uniquely identifies the resource to be shared.

keyName
Pointer to the name that uniquely identifies the resource.

Exception

IAccessError The shared resource object was not created. The memory may be exhausted, the handle limit on your platform may be exceeded, or the keyName may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Lock/Unlock

Use these methods to lock and unlock the resource.


[view class]
lock
public:
virtual ISharedResource& lock(long timeOut = - 1)
Acquires serialized access to the resource, preventing other threads of execution from accessing it. You can specify the value for timeout in milliseconds with -1 indicating an indefinite wait and 0 requesting an immediate return.

Locks can be be obtained multiple times on the same resource by the same thread. A corresponding number of unlocks must be performed to release the resource.

timeout
The number of milliseconds the caller is willing to wait to get the lock. If the lock cannot be gotten within that time period, then an exception is thrown.

Exception

IOutOfSystemResource The request failed because of a lock time out. (DD) IAccessError Unexpected error while accessing underlying system object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
unlock
public:
virtual ISharedResource& unlock()
Releases access to the resource, allowing other threads of execution to access it. If multiple locks have been done by the same thread, this only bumps down the lock count. Once the lock count reaches zero again, the resource will be released.

Exception

IAccessError Unexpected error while accessing underlying system object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Resource Information

Use these members to access shared resource information.


[view class]
keyName
public:
IString keyName() const
Returns the name used to identify this shared resource.

Return
The name of the shared resource, as an IString object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ISharedResource - Inherited Member Functions and Data

Inherited Public Functions

IResource

Inherited Public Data

Inherited Protected Functions

ISharedResource
IResource

Inherited Protected Data