$Id: README 83466 2008-10-27 19:35:53Z pollockt $

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.

"-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
                  Notify_Service, which is on by default.

!! 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 "TAO_CosNotify_Service" 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.

"-DefaultConsumerAdminFilterOp [op]" : Sets the default consumer admin filter operator [OR|AND].

"-DefaultSupplierAdminFilterOp [op]" : Sets the default consumer admin filter operator [OR|AND].

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.
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.
