README,v 1.6 2001/05/19 22:26:25 schmidt Exp
README for Notify_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": Specifes the <channel_name> to register with the
                             Naming Service.
                             The default is "NotifyEventChannel".

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

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:

"-MTDispatching"                     : Enable MT dispatching
"-DispatchingThreads [thread_count]" : How many threads for MT dispatching.
"-MTSourceEval"                      : Enable MT proxy consumer(source) filter evaluation.
"-SourceThreads [thread_count]"      : How many threads for source filter evaluation.
"-MTLookup"                          : Enable MT subscription table lookup.
"-LookupThreads [thread_count]"      : How many lookup threads.
"-MTListenerEval"                    : Enable MT proxy supplier (listener) filter evaluation.
"-ListenerThreads"                   : How many threads for listener filter evaluation.
"-Notify_TPReactor [threads]"        : Tells the service that the ORB
                                       is using a TP reactor and
                                       specifies the number of worker
                                       threads to deploy.
                                       Note that you might have to
                                       specify  the TP reactor in the
                                       svc.conf file.
                                       (see the ORB configutrations
                                       for details on this)

"-AsynchUpdates"                     : Send subscription and
                                       publication updates asynchronously.

"-AllocateTaskperProxy"              : Allocate worker tasks per
                                       proxy for the following
                                       options:
                                       "-MTDispatching",
                                       "-MTSourceEval"
                                       "-MTListenerEval"
                                       *see footnote below for explaination*

e.g. svc.conf
static Notify_Default_Event_Manager_Objects_Factory "-MTSourceEval -MTDispatching -DispatchingThreads 2"

This means that we want to enable MT proxy supplier filter evaluation
(default 1 thread) and MT 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 "-MTDispatching" and set "DispatchingThreads 1".
It means that there is 1 thread to perform the event dispatching to
consumers IRRESPECTIVE OF THE NUMBER OF PROXYSUPPLIERS.
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 dispaching 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, the "-MTSourceEval" specifies a thread pool for the filter
evauation at the proxyconsumer ("Source").
and the "-MTListenerEval" specifies a thread pool for the filter
evauation at the proxyconsumer ("Listener").

thanks,
Pradeep <pradeep@cs.wustl.edu>
