IPrivateResource

The IPrivateResource class defines a resource that is used within a single process.

IResource and its inherited classes represent resources in the user's problem domain. Objects of these classes name a particular resource. For example, a user wants to serialize access to the data in a window list collection. The user creates an IResource inherited class to represent the window list and then uses IResourceLock (preferred) or a function of IResource itself to lock and unlock the resource to serialize the access. You can use this class either alone (lock and unlock) or in combination with an IResourceLock, whose constructor locks the resource and whose destructor unlocks the resource. If you need the lock only for a block of code, use IResourceLock. Use static objects because you only need a single object of a particular IResource.

The static object pointer discussions exist because there is no language-defined way to ensure that static objects are constructed when needed. Also, they are always constructed even if they are never needed. Combining a static pointer to an object with a static function to reference the object and then creating the object, if necessary, defers creating the object until it is needed.

Use this class for resources that are limited to the same process (as opposed to a public resource that is used by more than one process via its name).

You can use this class as a static key to serialize access to a private resource. You can also use this class as a mechanism to ensure that the static resource is constructed prior to being used.

Some basic guidelines include the following:


IPrivateResource - Member Functions and Data by Group

Constructors & Destructor

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


[view class]
~IPrivateResource
public:
virtual ~IPrivateResource()
Destroys a private resource object.

Exception

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IPrivateResource
public:
IPrivateResource()
Constructs a private resource object. The only way to construct objects of this class is with the default constructor.
The default constructor. This is the only way to construct a private resource object.

Exception

IAccessError The private resource object was not created. The memory may be exhausted or the semaphore handle limit on your platform may be exceeded.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Lock/Unlock

Use these functions to lock and unlock the resource.


[view class]
lock
public:
virtual IPrivateResource& 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 IPrivateResource& 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


IPrivateResource - Inherited Member Functions and Data

Inherited Public Functions

IResource

Inherited Public Data

Inherited Protected Functions

IPrivateResource
IResource

Inherited Protected Data