home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / som30tk.zip / som30os2.zip / include / snglicls.idl < prev    next >
Text File  |  1996-12-24  |  4KB  |  96 lines
  1. //
  2. //   COMPONENT_NAME: somm
  3. //
  4. //   ORIGINS: 27
  5. //
  6. //
  7. //    25H7912  (C)  COPYRIGHT International Business Machines Corp. 1992,1996,1996
  8. //   All Rights Reserved
  9. //   Licensed Materials - Property of IBM
  10. //   US Government Users Restricted Rights - Use, duplication or
  11. //   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  12. //
  13. //#  @(#) /43 1.15 3/29/96 15:41:41 [12/24/96 07:41:13]
  14.  
  15.  
  16. #ifndef snglicls_idl
  17. #define snglicls_idl
  18.  
  19. #include <somcls.idl>
  20.  
  21.  
  22. interface SOMMSingleInstance
  23.                                  : SOMClass
  24. // Classes that specify SOMMSingleInstance as their metaclass (or
  25. // are derived from such a class) will only be allowed to have a
  26. // single instance. Such classes are called single instance classes.
  27. //
  28. // For example, if a class named Dog specified SOMMSingleInstance
  29. // as its explicit metaclass, only one dog object could be
  30. // instantiated. Repeated invocations of somNew on the Dog class
  31. // would simply return the same Dog instance.
  32.  
  33. // Note: it makes little or no sense for a metaclass to be a single
  34. // instance class because, in most cases, it would be impossible to
  35. // create subclasses of its first instance. (These subclasses would
  36. // need to be additional instances of the metaclass.)
  37. //
  38. // The (one) instance of a single instance class is always created
  39. // on the heap, either as a result of a user invoking somNew or
  40. // somNewNoInit on the single instance class, or by internal code
  41. // as a result of a user invoking any of the somRenew<...> object
  42. // creation calls on the single instance class. In this second
  43. // case, a proxy to the single instance is created in the location
  44. // pointed to by the Renew call. This is done in case the specified
  45. // location is not on the heap, and means that objects created
  46. // using Renew operations won't have users the caller is not aware
  47. // of (thus the memory can be reused when the caller is finished with
  48. // the object, which is one purpose of the Renew methods). The size
  49. // of a proxy to the single instance is 4 bytes (i.e., the proxy
  50. // contains no instance data, and consists solely of a method table
  51. // pointer). Thus, the proxy will always fit in the space reserved by
  52. // the caller for use by a Renew method.
  53. //
  54. // Once the single instance exists, subsequent invocations of somNew
  55. // or somNewNoInit return a pointer to the single instance.
  56. // Invocations of the somRenew<...> object creation methods that
  57. // point to the single instance do nothing; otherwise, a proxy to
  58. // the single instance is created in the location pointed to by the
  59. // Renew call (since a new instance of the class cannot be created).
  60. //
  61. // The single instance is reference counted, and is destroyed when
  62. // the count goes to zero.
  63. //
  64. // There are two ways to retrieve the single instance of a single
  65. // instance class:
  66. //
  67. //  1) Invoke sommGetSingleInstance on the single instance class.
  68. //     This is the preferred way when the user is statically aware that
  69. //     the class is a single instance class.
  70. //
  71. //  2) Invoke somNew or somNewNoInit on the class object of the using class.
  72. //
  73. {
  74.  
  75.         SOMObject sommGetSingleInstance();
  76.         // Returns the single instance of the using class. If
  77.         // there isn't one, then it creates one first with somNew.
  78.  
  79.         void sommFreeSingleInstance();
  80.         // Frees the single instance of the class.
  81.         // If there isn't one, then the method does nothing.
  82.  
  83.         #ifdef __SOMIDL__
  84.  
  85.         implementation {
  86.                 callstyle=idl;
  87.                 dllname = "somu.dll";
  88.                 releaseorder: sommGetSingleInstance, sommFreeSingleInstance;
  89.                 majorversion = 2;
  90.                 minorversion = 2;
  91.                 filestem = snglicls;
  92.         };
  93.         #endif /* __SOMIDL__ */
  94. };
  95. #endif
  96.