//
//   COMPONENT_NAME: somm
//
//   ORIGINS: 27
//
//
//    25H7912  (C)  COPYRIGHT International Business Machines Corp. 1992,1996,1996
//   All Rights Reserved
//   Licensed Materials - Property of IBM
//   US Government Users Restricted Rights - Use, duplication or
//   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
//
//#  @(#) /43 1.15 3/29/96 15:41:41 [12/22/96 21:13:43]


#ifndef snglicls_idl
#define snglicls_idl

#include <somcls.idl>


interface SOMMSingleInstance
                                 : SOMClass
// Classes that specify SOMMSingleInstance as their metaclass (or
// are derived from such a class) will only be allowed to have a
// single instance. Such classes are called single instance classes.
//
// For example, if a class named Dog specified SOMMSingleInstance
// as its explicit metaclass, only one dog object could be
// instantiated. Repeated invocations of somNew on the Dog class
// would simply return the same Dog instance.

// Note: it makes little or no sense for a metaclass to be a single
// instance class because, in most cases, it would be impossible to
// create subclasses of its first instance. (These subclasses would
// need to be additional instances of the metaclass.)
//
// The (one) instance of a single instance class is always created
// on the heap, either as a result of a user invoking somNew or
// somNewNoInit on the single instance class, or by internal code
// as a result of a user invoking any of the somRenew<...> object
// creation calls on the single instance class. In this second
// case, a proxy to the single instance is created in the location
// pointed to by the Renew call. This is done in case the specified
// location is not on the heap, and means that objects created
// using Renew operations won't have users the caller is not aware
// of (thus the memory can be reused when the caller is finished with
// the object, which is one purpose of the Renew methods). The size
// of a proxy to the single instance is 4 bytes (i.e., the proxy
// contains no instance data, and consists solely of a method table
// pointer). Thus, the proxy will always fit in the space reserved by
// the caller for use by a Renew method.
//
// Once the single instance exists, subsequent invocations of somNew
// or somNewNoInit return a pointer to the single instance.
// Invocations of the somRenew<...> object creation methods that
// point to the single instance do nothing; otherwise, a proxy to
// the single instance is created in the location pointed to by the
// Renew call (since a new instance of the class cannot be created).
//
// The single instance is reference counted, and is destroyed when
// the count goes to zero.
//
// There are two ways to retrieve the single instance of a single
// instance class:
//
//  1) Invoke sommGetSingleInstance on the single instance class.
//     This is the preferred way when the user is statically aware that
//     the class is a single instance class.
//
//  2) Invoke somNew or somNewNoInit on the class object of the using class.
//
{

        SOMObject sommGetSingleInstance();
        // Returns the single instance of the using class. If
        // there isn't one, then it creates one first with somNew.

        void sommFreeSingleInstance();
        // Frees the single instance of the class.
        // If there isn't one, then the method does nothing.

        #ifdef __SOMIDL__

        implementation {
                callstyle=idl;
                dllname = "somu.dll";
                releaseorder: sommGetSingleInstance, sommFreeSingleInstance;
                majorversion = 2;
                minorversion = 2;
                filestem = snglicls;
        };
        #endif /* __SOMIDL__ */
};
#endif
