File : gnatcom-create.ads
------------------------------------------------------------------------------
-- --
-- GNATCOM - Ada 95 COM/DCOM/COM+ Development Framework and Tools --
-- --
-- G N A T C O M . C R E A T E --
-- --
-- S p e c --
-- --
-- $Revision: 1.3 $
-- --
-- Copyright (C) 1999, 2000, 2001 David Botton --
-- --
-- This is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- ware Foundation; either version 2, or (at your option) any later ver- --
-- sion. It is distributed in the hope that it will be useful, but WITHOUT --
-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or --
-- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
-- for more details. You should have received a copy of the GNU General --
-- Public License distributed with this; see file COPYING. If not, write --
-- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
-- MA 02111-1307, USA. --
-- --
-- As a special exception, if other files instantiate generics from this --
-- unit, or you link this unit with other files to produce an executable, --
-- this unit does not by itself cause the resulting executable to be --
-- covered by the GNU General Public License. This exception does not --
-- however invalidate any other reasons why the executable file might be --
-- covered by the GNU Public License. --
-- --
-- More information about GNATCOM and the most current public version can --
-- be located on the web at http://www.adapower.com/gnatcom --
-- --
-- Support for GNATCOM is available from Ada Core Technologies, Inc. --
-- --
-- In the U.S., contact Ada Core Technologies at: --
-- Tel: +1 (212) 620 7300 ext 117 --
-- Fax: +1 (212) 807 0162 --
-- Email: sales@gnat.com --
-- --
-- In Europe and elsewhere, contact ACT Europe at: --
-- Tel: +33 1 49 70 67 16 --
-- Fax: +33 1 49 70 05 52 --
-- Email: sales@act-europe.fr --
------------------------------------------------------------------------------
-- Base package for creation of COM objects
with Interfaces.C;
package GNATCOM.Create is
Component_Count : aliased Interfaces.C.long := 0;
-- Number of components created that have not been deallocated
Server_Lock_Count : aliased Interfaces.C.long := 0;
-- Number of locks requested by clients on the server requesting the
-- server not shut down even if there are no outstanding components,
-- i.e. Component_Count > 0
hInstance : Interfaces.C.long := 0;
-- Contains the intstance handle of the container
InProcServer : Boolean := True;
-- Indicates to the framework that it is being used by an in-process
-- server
type Thread_Model is (Single, Multiple, Both);
-- The Thread_Model type tells GNATCOM to create objects that
-- conform to the following behaviors:
--
-- Single
-- * Objects in this container are only accessed from the thread they
-- were created in.
-- * Multiple instances of the object, may be in different threads.
-- Therefore, when creating objects of Thread_Model Single all global
-- variables must be protected, but variables contained in the
-- CoClass_Type records (CreateCOM generates a type derived from
-- GNATCOM.Create.COM_Interface.CoClass_Type for each CoClass, i.e..
-- COM Object, that contains the instance specific data for the COM
-- object) need not be protected since all invocation of COM methods
-- are guaranteed to be synchronized on the thread is was created on
-- regardless of what thread makes the method invocation.
-- * If need to access other COM objects from with in this object arise
-- only CoInitialize, OleInitialize, CoInitializeEx (0,
-- COINIT_APARTMENTTHREADED), or GNATCOM.Initialize.Initialize_COM
-- may be called (but is not needed to be called) in the thread that
-- it has been invoked by. Other tasks that are created may call the
-- other initializers if needed.
-- * GNATCOM.Initialize.Initialize_COM is called at startup of
-- the LocalServer version of the object
-- * In MS parlance, this object will be created in an STA = Single
-- Threaded Apartment
--
-- Multiple
-- * Objects in this container may be created in one thread and accessed
-- from any other
-- * This option is usually used only for objects in InProcServers that
-- need to call CoInitializeEx (0, COINIT_MULTITHREADED),
-- GNATCOM.Initialize.Initialize_Multi_Threaded or will have
-- internal tasks that will be calling back in to the object.
-- * Global and also Object specific data contained in the CoClass_Type
-- (See above in Single) must be protected since multiple concurrent
-- invocations of the object are possible
-- * If an object invokes from a thread that called CoInitialize,
-- OleInitialize, CoInitializeEx (0, COINIT_APARTMENTTHREADED),
-- or GNATCOM.Initialize.Initialize_COM, and the object is an
-- InProcServer (DLL) access to the object will be slower since
-- invocations must take place through a proxy.
-- * GNATCOM.Initialize.Initialize_COM_Multi_Threaded is called at
-- startup of the LocalServer version of the object
-- * Known in MS circles as a Free Threaded Object and are said to
-- run only in an MTA - Mutli Threaded Apartment
--
-- Both
-- * Objects in this container may be created in one thread and accessed
-- from any other
-- * Does not always suffer the above penalty for objects in
-- InprocServers since object will be accessed in the way the is
-- most efficient to the client based on how the thread the object
-- was was created in initialized itself with one of the
-- CoIntialize/GNATCOM.Initialize variants.
-- * This option is the same as Multiple for LocalServers (Exe's)
Use_Thread_Model : Thread_Model := Single;
-- The default thread model is Single and can be changed by adding the
-- following line to the genrated code in X-dll.adb in procedure main
-- for InprocServers:
--
-- procedure Main is
-- begin
-- GNATCOM.Create.Use_Thread_Model := GNATCOM.Create.Both;
-- -- or Multiple
-- ....
--
-- For the LocalServer version add in X-exe.adb:
-- add the line:
--
-- GNATCOM.Create.Use_Thread_Model := GNATCOM.Create.Both;
-- -- or Multiple
--
-- after the begin of the X.Exe procedure.
Main_Thread_ID : Interfaces.C.unsigned_long;
-- Local servers store the thread ID of the main thread here
procedure Can_Close;
-- Called with in the framework to determine if the server should
-- shutdown, i.e. when Component_Count and Server_Lock_Count both
-- equal zero
-- Notes:
-- Createing Singletons = Class Objects :
--
-- Modify the generated create function for a class to return a static
-- instance of the derived CoClass_Type. For example:
--
--
-- Singleton : Pointer_To_BeepClass_Type := null;
--
-- function Create
-- return GNATCOM.Create.COM_Interface.Pointer_To_COM_Interface
-- is
-- use type Interfaces.C.long;
-- begin
-- if Singleton = null then
-- Singleton := new BeepClass_Type;
-- end if;
--
-- Singleton.Ref_Count := Singleton.Ref_Count + 1;
-- GNATCOM.Create.Component_Count :=
-- GNATCOM.Create.Component_Count - 1;
-- GNATCOM.Create.COM_Interface.Create_Object (Singleton);
--
-- return Object;
-- end Create;
--
-- The additional Ref_Count is added to insure that no attempt to
-- free the Singelton object is made when the last interface is
-- destroyed.
--
-- The reduction of the Component_Count insures that server housing
-- the singleton will shutdown when there are no more connections to it.
--
-- If the object is in a LocalServer, other processes can attach to and
-- use the singleton object.
--
-- Removing the Component_Count reduction will cause a LocalServer to
-- remain in memory once started even if no interfaces are in use
-- and the original process that created it has since died.
end GNATCOM.Create;