home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IRESLOCK.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  17KB  |  300 lines
  1. #ifndef _IRESLOCK_
  2.   #define _IRESLOCK_
  3. /*******************************************************************************
  4. * FILE NAME: ireslock.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IResource        - The base resource definition class.                   *
  9. *     IPrivateResource - Private non-shared resource class.                    *
  10. *     ISharedResource  - Resource capable of being shared across processes.    *
  11. *     IResourceLock    -                                                       *
  12. *                                                                              *
  13. * COPYRIGHT:                                                                   *
  14. *   (C) Copyright IBM Corporation 1992                                         *
  15. *   All Rights Reserved                                                        *
  16. *   Licensed Materials * Property of IBM                                       *
  17. *                                                                              *
  18. * HISTORY:                                                                     *
  19. *******************************************************************************/
  20. #ifndef _IVBASE_
  21.   #include <ivbase.hpp>
  22. #endif
  23.  
  24. #ifndef _ISTRING_
  25.   #include <istring.hpp>
  26. #endif
  27.  
  28. /*----------------------------------------------------------------------------*/
  29. /* Align classes on four byte boundary.                                       */
  30. /*----------------------------------------------------------------------------*/
  31. #pragma pack(4)
  32.  
  33. class IResourceLock;
  34.  
  35. class IResource : public IVBase
  36. {
  37. typedef IVBase
  38.   Inherited;
  39. /*******************************************************************************
  40. *  The IResource class is the virtual base resource class.  Subclasses of
  41. *  this class are used to identify a serially reusable resource.  These
  42. *  resources can be limited to the current process (see IPrivateResource) or
  43. *  they can be shared across multiple processes (see ISharedResource).                            *
  44. *******************************************************************************/
  45. public:
  46. /*------------------------ Constructors/Destructor  ----------------------------
  47. | Instances of this class cannot be created.                                   |
  48. ------------------------------------------------------------------------------*/
  49.   IResource();
  50.   ~IResource();
  51. /*------------------------ Resource Locking ------------------------------------
  52. | lock   - Acquires serialized access to this resource.  The timeout value is  |
  53. |          specified in milliseconds with -1 indicating an indefinite wait     |
  54. |          and 0 requesting an immediate return.                               |
  55. | unlock - Releases the access to this resource.                               |
  56. ------------------------------------------------------------------------------*/
  57. IResource
  58.  &lock           ( long timeOut = -1),
  59.  &unlock         ( );
  60.  
  61.  
  62. protected:
  63. /*------------------------ Implementation --------------------------------------
  64. | The following function provides utilities used to implement this class:      |
  65. |   handle  -  Returns the handle for the resource.                            |
  66. ------------------------------------------------------------------------------*/
  67. virtual unsigned long
  68.  &handle        ( )  = 0;
  69.  
  70. long
  71.   lClReferenceCount;
  72.  
  73. IResourceLock
  74.  *reslockGate;
  75.  
  76. friend class IResourceLock;
  77. };
  78.  
  79. class IPrivateResource : public IResource
  80. {
  81. typedef IResource
  82.   Inherited;
  83. /*******************************************************************************
  84. *  The IPrivateResource class is used to define a resource that is used        *
  85. *  within a single process.                                                    *
  86. *                                                                              *
  87. *  You can use IPrivateResource as a static key that can be used to serialize  *
  88. *  access to a private resource.  You can also use a mechanism to ensure that  *
  89. *  the static resource is constructed prior to being used.  Some basic         *
  90. *  guidelines are:                                                             *
  91. *                                                                              *
  92. *     - Use a static pointer to the resource rather then a static object.      *
  93. *     - Always access the resource using a static function rather than         *
  94. *       directly using the static pointer.                                     *
  95. *     - When the resource is accessed through the static function, allocate    *
  96. *       it if the pointer is 0.                                                *
  97. *     - Provide a class that represents the static pointers for a particular   *
  98. *       class or component.  This class needs no constructor but requires a    *
  99. *       destructor that destroys the static objects used by the component.     *
  100. *                                                                              *
  101. *  EXAMPLE:  The following example uses the concepts described above.  The     *
  102. *  approach here uses the class IResourceLock to control the amount of time    *
  103. *  that the resource is serialized.  The example in ISharedResource describes  *
  104. *  controlling access without an IResourceLock class.                          *
  105. *                                                                              *
  106. *  class StaticPointers                                                        *
  107. *  {                                                                           *
  108. *  public:                                                                     *
  109. *    //  dtor to ensure static "objects" are destroyed                         *
  110. *    ~StaticPointers() {                                                       *
  111. *        if(pComponentKey())                                                   *
  112. *          delete pComponentKey; }                                             *
  113. *                                                                              *
  114. *  //  Function to retrieve the Resource Key                                   *
  115. *  IPrivateResource                                                            *
  116. *   &componentKey() {                                                          *
  117. *     if(pComponentKey() ==0)                                                  *
  118. *       pComponentKey = new IPrivateResource;                                  *
  119. *       return *pComponentKey;   }                                             *
  120. *                                                                              *
  121. *                                                                              *
  122. *  IPrivateResource                                                            *
  123. *   *pComponentKey;                                                            *
  124. *  };                                                                          *
  125. *                                                                              *
  126. *  //  Static object to ensure component statics are destructed                *
  127. *  StaticPointers componentStatics;                                            *
  128. *                                                                              *
  129. *                                                                              *
  130. *  // Function requiring serial access to component resource                   *
  131. *  Component :: foo()  {                                                       *
  132. *                                                                              *
  133. *    // Use an automatic IResourceLock to acquire the access to the resource   *
  134. *    IResourceLock(componentStatics::componentKey());                          *
  135. *                                                                              *
  136. *    .... code to access the resource                                          *
  137. *                                                                              *
  138. *  } // IResourceLock goes out of scope and releases access to the resource.   *
  139. *                                                                              *
  140. *******************************************************************************/
  141. public:
  142. /*------------------------ Constructors/Destructor -----------------------------
  143. | The only way to construct an instance of this class is by using the default
  144. | constructor, which does not take any arguments.                  |
  145. ------------------------------------------------------------------------------*/
  146.   IPrivateResource    ( );
  147. virtual
  148.   ~IPrivateResource   ( );
  149.  
  150. protected:
  151. /*------------------------ Implementation --------------------------------------
  152. | The following function provides utilities used to implement this class:      |
  153. |   handle - Returns the handle for the resource.                              |
  154. ------------------------------------------------------------------------------*/
  155. unsigned long
  156.  &handle              ( );
  157.  
  158. private:
  159.  
  160. unsigned long
  161.   ulClHandle;
  162.  
  163. friend class IResourceLock;
  164. };
  165.  
  166.  
  167. class ISharedResource : public IResource
  168. {
  169. typedef IResource
  170.   Inherited;
  171. /*******************************************************************************
  172. *  The ISharedResource class is used to define a resource that can be shared   *
  173. *  across multiple processes using a name provide on construction.             *                *
  174. *                                                                              *
  175. *                                                                              *
  176. *  Example:                                                                    *
  177. *                                                                              *
  178. *  // Use an ISharedResource class to determine if a resource is available.    *
  179. *  // If it is, do some work, else wait until later.                           *
  180. *                                                                              *
  181. *  ISharedResource pResource = new ISharedResource("PROFILE");                 *
  182. *                                                                              *
  183. *  try                                                                         *
  184. *  {                                                                           *
  185. *    pResource->lock(1);  // lock the resource if available now                *
  186. *    //   do some work                                                         *
  187. *    pResource->unlock(); // unlock the resource                               *
  188. *  }                                                                           *
  189. *  catch(IResourceExhausted exc)   // Failing lock() will throw exception      *
  190. *  {                                                                           *
  191. *    // Do not do anything because we will try again later                     *
  192. *  }                                                                           *
  193. *                                                                              *
  194. *  delete pResource;                                                           *
  195. *                                                                              *
  196. *                                                                              *
  197. *******************************************************************************/
  198. public:
  199. /*------------------------ Constructor/Destructor ------------------------------
  200. | The only way to construct an instance of this class is by providing a        |
  201. | character string that identifies the resource to be shared.                  |
  202. ------------------------------------------------------------------------------*/
  203.   ISharedResource   (const char* keyName);
  204. virtual
  205.   ~ISharedResource  ( );
  206.  
  207. /*------------------------ Accessors -------------------------------------------
  208. | This function provides a means of getting the accessible attributes of       |
  209. | instances of this class:                                                     |
  210. |   keyName - Returns the name used to identify this public resource.          |
  211. ------------------------------------------------------------------------------*/
  212. IString
  213.   keyName           ( );
  214.  
  215. protected:
  216.  
  217. /*------------------------ Implementation --------------------------------------
  218. | The following function provides utilities used to implement this class:      |
  219. |    handle - Returns the handle for the resource.                             |
  220. ------------------------------------------------------------------------------*/
  221. unsigned long
  222.  &handle            ( );
  223.  
  224. private:
  225.  
  226. unsigned long
  227.   ulClHandle;
  228. IString
  229.   strClKeyName;
  230.  
  231. friend class IResourceLock;
  232. };
  233.  
  234. class IResourceLock : public IVBase
  235. {
  236. typedef IVBase
  237.   Inherited;
  238. /*******************************************************************************
  239. *  The IResourceLock class locks a resource for a specified timeout.  The
  240. *  easiest use of the class is to declare a stack instance that is in scope
  241. *  for the period of time that the resource needs to be locked.  If the
  242. *  timeout is reached before the resource can be acquired, an
  243. *  IResourceExhausted exception is thrown.                                                                  *
  244. *                                                                              *
  245. *  Example:                                                                    *
  246. *                                                                              *
  247. *   static IPrivateResource collectionResource;                                *
  248. *                                                                              *
  249. *   addElement()                                                               *
  250. *   {                                                                          *
  251. *      //  Lock the resource                                                   *
  252. *      IResourceLock collectionLock(collectionResource);                       *
  253. *                                                                              *
  254. *      // Lock is removed on function exit                                     *
  255. *   }                                                                          *
  256. *                                                                              *
  257. *******************************************************************************/
  258. public:
  259.  
  260. /*------------------------ Constructor/Destructor ------------------------------
  261. | The only way to construct an instance of this class is by providing an       |
  262. | IResource reference and an optional timeout value.  The timeout value is     |
  263. | specified in milliseconds with -1 indicating an indefinite wait and 0        |
  264. | requesting an immediate return.                                              |
  265. ------------------------------------------------------------------------------*/
  266.   IResourceLock   ( IResource& resource,
  267.                     long       timeOut = -1);
  268.  
  269.   ~IResourceLock  ( );
  270.  
  271. protected:
  272. /*----------------------------- Implementation ---------------------------------
  273. | The following functions are used to implement the class.                     |
  274. |  setLock   - Acquires the resource.  The timeout value is specified in       |
  275. |              milliseconds with -1 indicating an indefinite wait and 0        |
  276. |              requesting an immediate return.                                 |
  277. |  clearLock - Releases the resource.                                          |
  278. ------------------------------------------------------------------------------*/
  279. IResourceLock
  280.  &setLock        ( long timeOut = -1),
  281.  &clearLock      ( );
  282.  
  283. private:
  284.  IResource* presCl;
  285.  
  286. friend  class IResource;
  287. };
  288.  
  289. /*----------------------------------------------------------------------------*/
  290. /* Resume compiler default packing.                                           */
  291. /*----------------------------------------------------------------------------*/
  292. #pragma pack()
  293.  
  294. /*--------------------------------- INLINES ----------------------------------*/
  295. #ifndef I_NO_INLINES
  296.   #include <ireslock.inl>
  297. #endif
  298.  
  299. #endif
  300.