diff options
Diffstat (limited to 'TAO/orbsvcs/Notify_Service/README')
| -rw-r--r-- | TAO/orbsvcs/Notify_Service/README | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/TAO/orbsvcs/Notify_Service/README b/TAO/orbsvcs/Notify_Service/README new file mode 100644 index 00000000000..3dc06134774 --- /dev/null +++ b/TAO/orbsvcs/Notify_Service/README @@ -0,0 +1,256 @@ +$Id$ + +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 Notify_Service 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 <factory_name> as the default name for the + Channel Factory + The default is "NotifyEventChannelFactory". + +"-Boot" : Flag asking that the <factory_name> 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 <file_name>. + 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. + +"-ChannelName channel_name" : Specifies the <channel_name> to register with the + Naming Service. + The default is "NotifyEventChannel". + +"-ORBRunThreads 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. + +!! 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 + + $ Notify_Service -ORBInitRef NameService=file://naming.ior + +Using the Boot option: +---------------------- +an example on how to locate the Notify Factory without the Naming Service - + +./Notify_Service -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. + +The svc.conf options: +---------------------- + +The "Notify_Default_Event_Manager_Objects_Factory" service object accepts the following options: + +"-DispatchingThreads [thread_count]" : Enables MT dispatching with the specified number + of threads. + +"-ListenerThreads" : How many threads for listener filter evaluation. + +"-AsynchUpdates" : Send subscription and + publication updates + asynchronously. + +"-AllocateTaskperProxy" : Allocate worker tasks per + proxy + *see footnote below for explanation* +"-AllowReconnect" : Allows consumers and suppliers to + reconnect to existing proxies. + +"-NoUpdates" : Globally disables subscription and + publication updates. + +All other options are deprecated and should not be used. + +e.g. svc.conf +static Notify_Default_Event_Manager_Objects_Factory "-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. +e.g. When you specify "DispatchingThreads 1". +It means that there is 1 thread to perform the event dispatching to +consumers IRRESPECTIVE OF THE NUMBER OF PROXYSUPPLIERS. 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 +PROXYSUPPLIER. 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 "-ListenerThreads 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 + + % NT_Notify_Server [-i value] + [-r] + [-s] + [-k] + [-t n] + [-d] + +2. Optional Command-line Arguments + + -i value + Install this program as an NT service, with specified startup + + -r + Remove this program from the Service Manager + -s + Start the service + + -k + Kill the service + + -t value + Set startup 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. + + a. First, you must initialize the service in the NT SCM + database. Run NT_Notify_Service with -in, where n is one of + the following 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_AUTO_START is default option. + + b. Now you are ready to run the actual service. Run + NT_Notify_Service again, this time with -s option. If the + service starts successfully, it will ring the system + bell every second or so until the service is stopped. + + c. To stop service execution, run NT_Notify_Service with the + -k option. + + d. To remove the service from the Service Control Manager + database, run NT_Notify_Service with -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 NT_Notify_Service with + -tn option. n is as explained above for -i. + + In order to debug the service's execution itself, use the -d + option. |