This directory contains files that implement a server for the TAO Notification Service. In addition, it contains files that run the TAO Notification Service as a Windows NT Service. Both of these services are described below. How to Run the TAO Notification Service ======================================= The tao_cosnotification executable starts up a Notification Service factory and registers it with the Naming Service under the name "NotifyEventChannelFactory" Command line arguments: ---------------------- "-?" : shows the options. "-Factory factory_name" : Uses the as the default name for the Channel Factory The default is "NotifyEventChannelFactory". "-Boot" : Flag asking that the be registered in the IOR table. The option is disabled by default. See the "Using the Boot option" section below. "-NameSvc" : Registers the Factory and if specified, an Event Channel with the Naming Service. if this option is used, a Naming Service must be accessible. This option is enabled by default. "-NoNameSvc" : Asks to skip any registration with the Naming Service. This option is disabled by default. "-IORoutput file_name" : The IOR is output to the file . By default, the IOR is printed out. "-Channel" : If this option is specified, a EventChannel is created and registered with the Naming Service. This option is disabled by default. This option can be specified multiple times, each option will result in a created and registered EventChannel "-ChannelName channel_name" : Specifies the to register with the Naming Service. The default is "NotifyEventChannel". "-RunThreads nthreads" : Number of threads to run the ORB::run method. "-UseSeparateDispatchingORB 1|0" : Indicates whether the service should create and and use a separate ORB dedicated to dispatching of events. "-ShutdownORB 1|0" : Indicates that we have to shutdown the default ORB, 1 by default "-ShutdownDispatchingORB 1|0" : Indicates that we have to shutdown the dispatching ORB, 1 by default "-Timeout msec" : Applies a relative round-trip timeout of msec microseconds to the main ORB and, if -UseSeparateDispatchingORB 1 is specified, to the dispatching ORB. This requires the 'corba_messaging' MPC feature during building of the tao_cosnotification, which is on by default. "-LoggingInterval seconds" : Sets up a logging interval timer for the ORB's reactor. This is required to use the ACE Logging Service features such as file sizing and rotation. See the example below. !! The -Notify_TPReactor option is deprecated!! use the -ORBRunThreads option instead. "-Notify_TPReactor [threads]": Tells the Notify Service that the ORB will use a TP reactor and specifies the number of worker threads to utilize. Note that the svc.conf file must instruct the ORB to use a TP reactor e.g. static Resource_Factory "-ORBReactorType tp -ORBReactorMaskSignals 0" Please look up the ORB configuration options to get more information on this. Running the Service: ------------------- 1. Start the Naming Service from $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service -m 1 if you are using the "-NameSvc" options. 2.Start the Notify_Service from this directory. You should see a message saying that the service has been started. Note: ==== By default, the Naming Service disables multicast discovery. The "-m 1" option enables the Naming Service to be resolved via multicast. If you do not wish to do this, then use the -ORBInitRef option in which case the Naming Service should be started as: $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service -o naming.ior and the Notify_Service as $ tao_cosnotification -ORBInitRef NameService=file://naming.ior Using the Boot option: ---------------------- an example on how to locate the Notify Factory without the Naming Service - ./tao_cosnotification -Boot -NoNameSvc -d -ORBobjrefstyle url -ORBEndPoint "iiop://flamenco.cs:9999" The Factory object reference is not registered with the Naming Service. "-Boot" binds the Factory object reference with "NotifyEventChannelFactory" in the IOR table. See the $TAO_ROOT/docs/Options.html for details on "-ORBEndPoint" A client program can obtain the factory object reference in the following manner: ./client -ORBInitRef "NotifyEventChannelFactory=corbaloc:iiop:flamenco.cs:9999/NotifyEventChannelFactory" Note that the client uses: resolve_initial_references ("NotifyEventChannelFactory"); to obtain the object reference. Using the ACE Logging Service: ------------------------------ Start the tao_cosnotification executable with the debug options desired and the -LoggingInterval option: ./tao_cosnotification -ORBDebugLevel 10 -ORBVerboseLogging 1 -ORBSvcConf ns.conf -LoggingInterval 5 Configure the logging service in the ns.conf file: dynamic Logging_Strategy Service_Object * ACE:_make_ACE_Logging_Strategy() "-s NS -f OSTREAM -t 0 " The svc.conf options: ---------------------- The "TAO_CosNotify_Service" service object accepts the following options: "-AllocateTaskperProxy" : Allocate worker tasks per proxy *see footnote below for explanation* "-AllowReconnect" : Allows consumers and suppliers to reconnect to existing proxies. "-AsynchUpdates" : Send subscription and publication updates asynchronously. "-DefaultConsumerAdminFilterOp [op]" : Sets the default consumer admin filter operator. op can be either "OR" or "AND". The default is "OR" to be consistent with older releases of TAO. "-DefaultSupplierAdminFilterOp [op]" : Sets the default supplier admin filter operator. op can be either "OR" or "AND". The default is "OR" to be consistent with older releases of TAO. "-DispatchingThreads [thread_count]" : Enables MT dispatching with the specified number of threads. This option supercedes the deprecated ListenerThreads, MTListenerEval and MTDispatching options. Note that "AllocateTaskperProxy" affects how this value is applied. "-NoUpdates" : Globally disables subscription and publication updates. "-ValidateClient" : Creates a thread that periodically walks the topology tree visiting each proxy and checking the liviness of the peer. A peer which had ordinary activity within the validation time period is considered alive. Otherwise the peer's _non_existent() operation is invoked. If this fails the proxy's disconnect operation is invoked. "-ValidateClientDelay [sec]" : Specifies the initial delay from the start of the validator task until the first pass through the topology. If left at the default value of 0, the validator taks will start immediately. A long delay is useful when the Notify service restarts after a shutdown and has to repopulate its topology from a persistent store, which takes time. "-ValidateClientInterval [sec]" : Specifies how frequently after the first pass to revisit the topology to further validate clients. The default value of 0 means validation will only happen once. "-SourceThreads [thread_count]" : Specifies the number of threads for each supplier admin or proxy consumer. See the note below for details about thread assignments. This option supercedes the deprecated LookupThreads, MTSourceEval, and MTLookup options. All other options are deprecated and should not be used. e.g. svc.conf static TAO_CosNotify_Service "-DispatchingThreads 2" This means that we want to enable event dispatching with 2 threads. ---------------------------------------------------------------- What does the "-AllocateTaskperProxy" option do? A Task here implies a thread pool that performs a fixed work in the Notify Service. e.g. When you specify "-DispatchingThreads 1" this means there is 1 thread to perform the event dispatching to consumers IRRESPECTIVE OF THE NUMBER OF PROXY SUPPLIERS. It also means that events destined for each consumer will be queued to a buffer for that consumer. Therefore, you can also think of this option as Enable Consumer-side Buffering of Events. This is the default case. When you specify "-AllocateTaskperProxy" it asks notify to create a dispatching task with the specified thread pool size PER PROXY SUPPLIER. So if you use this option and connect 50 consumers with 1 thread for the dispatching task you will have created 50 dispatching threads! so use this option with care and you might not need it in most cases. Why have this feature in the first place? The intent is to allow the software architect of a Notify based system, fine control over where and how much thread resources are deployed. e.g. a channel could have 2 proxy suppliers - the first one delivers an important event in huge quantities. A dedicated thread pool to this proxy will ensure better throughput to it's consumers. (Eventually I want to be able to set the thread pool size via a QoS property) Similarly "-SourceThreads 2" specifies a thread pool for use by the supplier-side processing. This enables Buffering on the Supplier-side, with the thread pool being used to process supplier side filters and push the events to the Consumer side. How to use the NT_Notify_Service ================================ To set the options for the TAO Notification Service, go to the Services icon in the Settings group under the start menu (start menu -> settings -> services). There, highlight the NT_Notify_Service, which is the name used by the Notification Service when it is registered. After it's highlighted, you should see at the bottom of the dialog box an area to specify options. Just enter the options you wish in that edit box and everything should just work. However, some options, such as -ORBDebugLevel, won't work since an NT service can't write output to standard out. 1. Syntax % tao_nt_cosnotification [-i n] [-c [args]] [-r] [-s] [-k] [-t n] [-d] 2. Optional Command-line Arguments -i [n] Install this program as an NT service, with specified startup mode -c [args] Query or supply command line arguments for NT service. -r Remove this program from the Service Manager -s Start the service -k Kill the service -t n Set startup mode for an existing service -d Debug; run as a regular application 3. Usage To see different stages of an NT service application, you have to run the program several times, with different options. Please note: run with only one option at a time. Only the Administrator can run commands that modify state such as the -i or -c options. a. First, you must initialize the service in the NT SCM database. Run tao_nt_cosnotification with -i [n], where n is a number from 1 to 4, corresponding to these startup options: // Start Type (from WinNT.h) // #define SERVICE_SYSTEM_START 0x00000001 #define SERVICE_AUTO_START 0x00000002 #define SERVICE_DEMAND_START 0x00000003 #define SERVICE_DISABLED 0x00000004 If only -i is specified, SERVICE_DEMAND_START is default option. This option may only be run as Administrator. b. For System or Auto start modes, or even Demand start and using the -s option to start, any command line options, such as endpoint specification or IOR publication, must be stored in the Windows registry. Use tao_nt_cosnotification -c with no additional arguments to see the current command line setting. Use tao_nt_cosnotification -c "args" to provide a new command line for the registered name service. Be sure to quote the args string. For example: tao_nt_cosnotification -c "-ORBListenEndpoints iiop://%computername%:2809" will yield: tao_nt_cosnotification -c -ORBListenEndpoints iiop://VIRTWIND:2809 Notice the environment variable used in the argument string was expanded. c. Now you are ready to run the actual service. Run tao_nt_cosnotification -s. d. To stop service execution, run tao_nt_cosnotification -k. c. To remove the service from the Service Control Manager database, run tao_nt_cosnotification -r. In addition, once you have initialized this service (by using the -i option) you can change its startup type to one of the other values above. To do this, run tao_nt_cosnotification -t n, where n is a number corresponding to one of the startup modes listed above. In order to debug the service's execution itself, use the -d option.