home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
IRESLOCK.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
17KB
|
300 lines
#ifndef _IRESLOCK_
#define _IRESLOCK_
/*******************************************************************************
* FILE NAME: ireslock.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IResource - The base resource definition class. *
* IPrivateResource - Private non-shared resource class. *
* ISharedResource - Resource capable of being shared across processes. *
* IResourceLock - *
* *
* COPYRIGHT: *
* (C) Copyright IBM Corporation 1992 *
* All Rights Reserved *
* Licensed Materials * Property of IBM *
* *
* HISTORY: *
*******************************************************************************/
#ifndef _IVBASE_
#include <ivbase.hpp>
#endif
#ifndef _ISTRING_
#include <istring.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
class IResourceLock;
class IResource : public IVBase
{
typedef IVBase
Inherited;
/*******************************************************************************
* The IResource class is the virtual base resource class. Subclasses of
* this class are used to identify a serially reusable resource. These
* resources can be limited to the current process (see IPrivateResource) or
* they can be shared across multiple processes (see ISharedResource). *
*******************************************************************************/
public:
/*------------------------ Constructors/Destructor ----------------------------
| Instances of this class cannot be created. |
------------------------------------------------------------------------------*/
IResource();
~IResource();
/*------------------------ Resource Locking ------------------------------------
| lock - Acquires serialized access to this resource. The timeout value is |
| specified in milliseconds with -1 indicating an indefinite wait |
| and 0 requesting an immediate return. |
| unlock - Releases the access to this resource. |
------------------------------------------------------------------------------*/
IResource
&lock ( long timeOut = -1),
&unlock ( );
protected:
/*------------------------ Implementation --------------------------------------
| The following function provides utilities used to implement this class: |
| handle - Returns the handle for the resource. |
------------------------------------------------------------------------------*/
virtual unsigned long
&handle ( ) = 0;
long
lClReferenceCount;
IResourceLock
*reslockGate;
friend class IResourceLock;
};
class IPrivateResource : public IResource
{
typedef IResource
Inherited;
/*******************************************************************************
* The IPrivateResource class is used to define a resource that is used *
* within a single process. *
* *
* You can use IPrivateResource as a static key that can be used to serialize *
* access to a private resource. You can also use a mechanism to ensure that *
* the static resource is constructed prior to being used. Some basic *
* guidelines are: *
* *
* - Use a static pointer to the resource rather then a static object. *
* - Always access the resource using a static function rather than *
* directly using the static pointer. *
* - When the resource is accessed through the static function, allocate *
* it if the pointer is 0. *
* - Provide a class that represents the static pointers for a particular *
* class or component. This class needs no constructor but requires a *
* destructor that destroys the static objects used by the component. *
* *
* EXAMPLE: The following example uses the concepts described above. The *
* approach here uses the class IResourceLock to control the amount of time *
* that the resource is serialized. The example in ISharedResource describes *
* controlling access without an IResourceLock class. *
* *
* class StaticPointers *
* { *
* public: *
* // dtor to ensure static "objects" are destroyed *
* ~StaticPointers() { *
* if(pComponentKey()) *
* delete pComponentKey; } *
* *
* // Function to retrieve the Resource Key *
* IPrivateResource *
* &componentKey() { *
* if(pComponentKey() ==0) *
* pComponentKey = new IPrivateResource; *
* return *pComponentKey; } *
* *
* *
* IPrivateResource *
* *pComponentKey; *
* }; *
* *
* // Static object to ensure component statics are destructed *
* StaticPointers componentStatics; *
* *
* *
* // Function requiring serial access to component resource *
* Component :: foo() { *
* *
* // Use an automatic IResourceLock to acquire the access to the resource *
* IResourceLock(componentStatics::componentKey()); *
* *
* .... code to access the resource *
* *
* } // IResourceLock goes out of scope and releases access to the resource. *
* *
*******************************************************************************/
public:
/*------------------------ Constructors/Destructor -----------------------------
| The only way to construct an instance of this class is by using the default
| constructor, which does not take any arguments. |
------------------------------------------------------------------------------*/
IPrivateResource ( );
virtual
~IPrivateResource ( );
protected:
/*------------------------ Implementation --------------------------------------
| The following function provides utilities used to implement this class: |
| handle - Returns the handle for the resource. |
------------------------------------------------------------------------------*/
unsigned long
&handle ( );
private:
unsigned long
ulClHandle;
friend class IResourceLock;
};
class ISharedResource : public IResource
{
typedef IResource
Inherited;
/*******************************************************************************
* The ISharedResource class is used to define a resource that can be shared *
* across multiple processes using a name provide on construction. * *
* *
* *
* Example: *
* *
* // Use an ISharedResource class to determine if a resource is available. *
* // If it is, do some work, else wait until later. *
* *
* ISharedResource pResource = new ISharedResource("PROFILE"); *
* *
* try *
* { *
* pResource->lock(1); // lock the resource if available now *
* // do some work *
* pResource->unlock(); // unlock the resource *
* } *
* catch(IResourceExhausted exc) // Failing lock() will throw exception *
* { *
* // Do not do anything because we will try again later *
* } *
* *
* delete pResource; *
* *
* *
*******************************************************************************/
public:
/*------------------------ Constructor/Destructor ------------------------------
| The only way to construct an instance of this class is by providing a |
| character string that identifies the resource to be shared. |
------------------------------------------------------------------------------*/
ISharedResource (const char* keyName);
virtual
~ISharedResource ( );
/*------------------------ Accessors -------------------------------------------
| This function provides a means of getting the accessible attributes of |
| instances of this class: |
| keyName - Returns the name used to identify this public resource. |
------------------------------------------------------------------------------*/
IString
keyName ( );
protected:
/*------------------------ Implementation --------------------------------------
| The following function provides utilities used to implement this class: |
| handle - Returns the handle for the resource. |
------------------------------------------------------------------------------*/
unsigned long
&handle ( );
private:
unsigned long
ulClHandle;
IString
strClKeyName;
friend class IResourceLock;
};
class IResourceLock : public IVBase
{
typedef IVBase
Inherited;
/*******************************************************************************
* The IResourceLock class locks a resource for a specified timeout. The
* easiest use of the class is to declare a stack instance that is in scope
* for the period of time that the resource needs to be locked. If the
* timeout is reached before the resource can be acquired, an
* IResourceExhausted exception is thrown. *
* *
* Example: *
* *
* static IPrivateResource collectionResource; *
* *
* addElement() *
* { *
* // Lock the resource *
* IResourceLock collectionLock(collectionResource); *
* *
* // Lock is removed on function exit *
* } *
* *
*******************************************************************************/
public:
/*------------------------ Constructor/Destructor ------------------------------
| The only way to construct an instance of this class is by providing an |
| IResource reference and an optional timeout value. The timeout value is |
| specified in milliseconds with -1 indicating an indefinite wait and 0 |
| requesting an immediate return. |
------------------------------------------------------------------------------*/
IResourceLock ( IResource& resource,
long timeOut = -1);
~IResourceLock ( );
protected:
/*----------------------------- Implementation ---------------------------------
| The following functions are used to implement the class. |
| setLock - Acquires the resource. The timeout value is specified in |
| milliseconds with -1 indicating an indefinite wait and 0 |
| requesting an immediate return. |
| clearLock - Releases the resource. |
------------------------------------------------------------------------------*/
IResourceLock
&setLock ( long timeOut = -1),
&clearLock ( );
private:
IResource* presCl;
friend class IResource;
};
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
/*--------------------------------- INLINES ----------------------------------*/
#ifndef I_NO_INLINES
#include <ireslock.inl>
#endif
#endif