TAO/orbsvcs/Notify_Service/README

   1
   2
   3 This directory contains files that implement a server for the TAO
   4 Notification Service.  In addition, it contains files that run the TAO
   5 Notification Service as a Windows NT Service.  Both of these services
   6 are described below.
   7
   8 How to Run the TAO Notification Service
   9 =======================================
  10
  11 The tao_cosnotification executable starts up a Notification Service factory
  12 and registers it with the Naming Service under the name
  13 "NotifyEventChannelFactory"
  14
  15 Command line arguments:
  16 ----------------------
  17 "-?"                    : shows the options.
  18
  19 "-Factory factory_name" : Uses the <factory_name> as the default name for the
  20                           Channel Factory
  21                           The default is "NotifyEventChannelFactory".
  22
  23 "-Boot"                 : Flag asking that the <factory_name> be registered
  24                           in the IOR table.
  25                           The option is disabled by default.
  26                           See the "Using the Boot option" section below.
  27
  28 "-NameSvc"              : Registers the Factory and if specified, an Event
  29                           Channel with the Naming Service.
  30                           if this option is used, a Naming Service must
  31                           be accessible.
  32                           This option is enabled by default.
  33
  34 "-NoNameSvc"            : Asks to skip any registration with the
  35                           Naming Service.
  36                           This option is disabled by default.
  37
  38 "-IORoutput file_name"  : The IOR is output to the file <file_name>.
  39                           By default, the IOR is printed out.
  40
  41 "-Channel"              : If this option is specified, a EventChannel is
  42                           created and registered with the Naming Service.
  43                           This option is disabled by default. This option can
  44                           be specified multiple times, each option will result
  45                           in a created and registered EventChannel
  46
  47
  48 "-ChannelName channel_name" : Specifies the <channel_name> to register with the
  49                               Naming Service.
  50                               The default is "NotifyEventChannel".
  51
  52 "-RunThreads nthreads"   : Number of threads to run the
  53                            ORB::run method.
  54
  55 "-UseSeparateDispatchingORB 1|0"
  56                             : Indicates whether the service should create and
  57                               and use a separate ORB dedicated to dispatching of
  58                               events.
  59
  60 "-ShutdownORB 1|0" : Indicates that we have to shutdown the default ORB,
  61                      1 by default
  62
  63 "-ShutdownDispatchingORB 1|0" : Indicates that we have to shutdown the
  64                                 dispatching ORB, 1 by default
  65
  66 "-Timeout msec" : Applies a relative round-trip timeout of msec microseconds
  67                   to the main ORB and, if -UseSeparateDispatchingORB 1 is
  68                   specified, to the dispatching ORB.  This requires the
  69                   'corba_messaging' MPC feature during building of the
  70                   tao_cosnotification, which is on by default.
  71
  72 "-LoggingInterval seconds" : Sets up a logging interval timer for the ORB's
  73                              reactor.  This is required to use the ACE
  74                              Logging Service features such as file sizing
  75                              and rotation.  See the example below.
  76
  77 !! The -Notify_TPReactor option is deprecated!! use the -ORBRunThreads
  78 option instead.
  79
  80 "-Notify_TPReactor [threads]": Tells the Notify Service that the ORB
  81                                will use a TP reactor and specifies the
  82                                number of worker threads to utilize.
  83
  84
  85 Note that the svc.conf file must instruct the ORB to use a TP reactor
  86 e.g. static Resource_Factory "-ORBReactorType tp -ORBReactorMaskSignals 0"
  87 Please look up the ORB configuration options to get more information
  88 on this.
  89
  90 Running the Service:
  91 -------------------
  92 1. Start the Naming Service from
  93
  94 $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service -m 1
  95
  96 if you are using the "-NameSvc" options.
  97
  98 2.Start the Notify_Service from this directory. You should see a message saying
  99   that the service has been started.
 100
 101    Note:
 102    ====
 103    By default, the Naming Service disables multicast discovery.
 104    The "-m 1" option enables the Naming Service to be resolved via
 105    multicast.
 106
 107    If you do not wish to do this, then use the
 108    -ORBInitRef option in which case the Naming Service should be started
 109    as:
 110
 111    $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service -o naming.ior
 112
 113    and the Notify_Service as
 114
 115    $ tao_cosnotification -ORBInitRef NameService=file://naming.ior
 116
 117 Using the Boot option:
 118 ----------------------
 119 an example on how to locate the Notify Factory without the Naming Service -
 120
 121 ./tao_cosnotification -Boot -NoNameSvc -d -ORBobjrefstyle url -ORBEndPoint "iiop://flamenco.cs:9999"
 122
 123 The Factory object reference is not registered with the Naming Service.
 124 "-Boot" binds the Factory object reference with "NotifyEventChannelFactory" in
 125 the IOR table.
 126 See the $TAO_ROOT/docs/Options.html for details on "-ORBEndPoint"
 127
 128 A client program can obtain the factory object reference in the following
 129 manner:
 130 ./client -ORBInitRef "NotifyEventChannelFactory=corbaloc:iiop:flamenco.cs:9999/NotifyEventChannelFactory"
 131
 132 Note that the client uses:
 133  resolve_initial_references ("NotifyEventChannelFactory");
 134 to obtain the object reference.
 135
 136 Using the ACE Logging Service:
 137 ------------------------------
 138
 139 Start the tao_cosnotification executable with the debug options desired and
 140 the -LoggingInterval option:
 141
 142 ./tao_cosnotification -ORBDebugLevel 10 -ORBVerboseLogging 1 -ORBSvcConf ns.conf -LoggingInterval 5
 143
 144 Configure the logging service in the ns.conf file:
 145 dynamic Logging_Strategy Service_Object * ACE:_make_ACE_Logging_Strategy() "-s NS -f OSTREAM -t 0 "
 146
 147
 148
 149 The svc.conf options:
 150 ----------------------
 151
 152 The "TAO_CosNotify_Service" service object accepts the following options:
 153
 154 "-AllocateTaskperProxy"              : Allocate worker tasks per proxy
 155                                        *see footnote below for explanation*
 156
 157 "-AllowReconnect"                    : Allows consumers and suppliers to
 158                                        reconnect to existing proxies.
 159
 160 "-AsynchUpdates"                     : Send subscription and publication
 161                                        updates asynchronously.
 162
 163 "-DefaultConsumerAdminFilterOp [op]" : Sets the default consumer admin filter
 164                                        operator. op can be either "OR" or
 165                                        "AND". The default is "OR" to be
 166                                        consistent with older releases of TAO.
 167
 168 "-DefaultSupplierAdminFilterOp [op]" : Sets the default supplier admin filter
 169                                        operator. op can be either "OR" or
 170                                        "AND". The default is "OR" to be
 171                                        consistent with older releases of TAO.
 172
 173 "-DispatchingThreads [thread_count]" : Enables MT dispatching with the
 174                                        specified number of threads. This
 175                                        option supercedes the deprecated
 176                                        ListenerThreads, MTListenerEval and
 177                                        MTDispatching options. Note that
 178                                        "AllocateTaskperProxy" affects how this
 179                                        value is applied.
 180
 181 "-NoUpdates"                         : Globally disables subscription and
 182                                        publication updates.
 183
 184 "-ValidateClient"                    : Creates a thread that periodically
 185                                        walks the topology tree visiting each
 186                                        proxy and checking the liviness of
 187                                        the peer. A peer which had ordinary
 188                                        activity within the validation time
 189                                        period is considered alive. Otherwise
 190                                        the peer's _non_existent() operation
 191                                        is invoked. If this fails the proxy's
 192                                        disconnect operation is invoked.
 193
 194 "-ValidateClientDelay [sec]"         : Specifies the initial delay from the
 195                                        start of the validator task until the
 196                                        first pass through the topology. If
 197                                        left at the default value of 0, the
 198                                        validator taks will start immediately.
 199                                        A long delay is useful when the Notify
 200                                        service restarts after a shutdown and
 201                                        has to repopulate its topology from a
 202                                        persistent store, which takes time.
 203
 204 "-ValidateClientInterval [sec]"      : Specifies how frequently after the
 205                                        first pass to revisit the topology
 206                                        to further validate clients. The
 207                                        default value of 0 means validation
 208                                        will only happen once.
 209
 210 "-SourceThreads [thread_count]"      : Specifies the number of threads for each
 211                                        supplier admin or proxy consumer. See
 212                                        the note below for details about thread
 213                                        assignments. This option supercedes the
 214                                        deprecated LookupThreads, MTSourceEval,
 215                                        and MTLookup options.
 216
 217 All other options are deprecated and should not be used.
 218
 219 e.g. svc.conf
 220 static TAO_CosNotify_Service "-DispatchingThreads 2"
 221
 222 This means that we want to enable event dispatching with 2 threads.
 223
 224 ----------------------------------------------------------------
 225 What does the "-AllocateTaskperProxy" option do?
 226
 227 A Task here implies a thread pool that performs a fixed work in the
 228 Notify Service. e.g. When you specify "-DispatchingThreads 1" this
 229 means there is 1 thread to perform the event dispatching to consumers
 230 IRRESPECTIVE OF THE NUMBER OF PROXY SUPPLIERS. It also means that
 231 events destined for each consumer will be queued to a buffer for that
 232 consumer.  Therefore, you can also think of this option as Enable
 233 Consumer-side Buffering of Events.
 234
 235 This is the default case.
 236
 237 When you specify "-AllocateTaskperProxy" it asks notify to create a
 238 dispatching task with the specified thread pool size PER PROXY
 239 SUPPLIER.  So if you use this option and connect 50 consumers with 1
 240 thread for the dispatching task you will have created 50 dispatching
 241 threads! so use this option with care and you might not need it in
 242 most cases.
 243
 244 Why have this feature in the first place?  The intent is to allow the
 245 software architect of a Notify based system, fine control over where
 246 and how much thread resources are deployed.  e.g. a channel could have
 247 2 proxy suppliers - the first one delivers an important event in huge
 248 quantities.  A dedicated thread pool to this proxy will ensure better
 249 throughput to it's consumers. (Eventually I want to be able to set the
 250 thread pool size via a QoS property)
 251
 252 Similarly "-SourceThreads 2" specifies a thread pool for use by the
 253 supplier-side processing. This enables Buffering on the Supplier-side,
 254 with the thread pool being used to process supplier side filters and
 255 push the events to the Consumer side.
 256
 257 How to use the NT_Notify_Service
 258 ================================
 259
 260 To set the options for the TAO Notification Service, go to the Services
 261 icon in the Settings group under the start menu (start menu ->
 262 settings -> services).  There, highlight the NT_Notify_Service, which
 263 is the name used by the Notification Service when it is registered.
 264 After it's highlighted, you should see at the bottom of the dialog box
 265 an area to specify options.  Just enter the options you wish in that
 266 edit box and everything should just work.  However, some options, such
 267 as -ORBDebugLevel, won't work since an NT service can't write output
 268 to standard out.
 269
 270 1. Syntax
 271
 272         % tao_nt_cosnotification [-i n]
 273                                  [-c [args]]
 274                                  [-r]
 275                                  [-s]
 276                                  [-k]
 277                                  [-t n]
 278                                  [-d]
 279
 280 2. Optional Command-line Arguments
 281
 282         -i [n]
 283                 Install this program as an NT service, with specified startup mode
 284
 285         -c [args]
 286                 Query or supply command line arguments for NT service.
 287
 288         -r
 289                 Remove this program from the Service Manager
 290         -s
 291                 Start the service
 292
 293         -k
 294                 Kill the service
 295
 296         -t n
 297                 Set startup mode for an existing service
 298
 299         -d
 300                 Debug; run as a regular application
 301
 302 3. Usage
 303
 304         To see different stages of an NT service application, you have
 305         to run the program several times, with different options.
 306         Please note: run with only one option at a time. Only the
 307         Administrator can run commands that modify state such as the -i
 308         or -c options.
 309
 310         a. First, you must initialize the service in the NT SCM
 311            database.  Run tao_nt_cosnotification with -i [n], where n is a
 312            number from 1 to 4, corresponding to these startup options:
 313
 314            // Start Type (from WinNT.h)
 315            //
 316            #define SERVICE_SYSTEM_START    0x00000001
 317            #define SERVICE_AUTO_START      0x00000002
 318            #define SERVICE_DEMAND_START    0x00000003
 319            #define SERVICE_DISABLED        0x00000004
 320
 321            If only -i is specified, SERVICE_DEMAND_START is default option.
 322            This option may only be run as Administrator.
 323
 324         b. For System or Auto start modes, or even Demand start and using the
 325            -s option to start, any command line options, such as endpoint
 326            specification or IOR publication, must be stored in the Windows
 327            registry. Use tao_nt_cosnotification -c with no additional arguments to
 328            see the current command line setting. Use tao_nt_cosnotification -c "args"
 329            to provide a new command line for the registered name service. Be
 330            sure to quote the args string. For example:
 331
 332            tao_nt_cosnotification -c "-ORBListenEndpoints iiop://%computername%:2809"
 333
 334            will yield:
 335            tao_nt_cosnotification -c
 336            -ORBListenEndpoints iiop://VIRTWIND:2809
 337
 338            Notice the environment variable used in the argument string was
 339            expanded.
 340
 341         c. Now you are ready to run the actual service. Run
 342            tao_nt_cosnotification -s.
 343
 344         d. To stop service execution, run tao_nt_cosnotification -k.
 345
 346         c. To remove the service from the Service Control Manager
 347            database, run tao_nt_cosnotification -r.
 348
 349         In addition, once you have initialized this service (by using
 350         the -i option) you can change its startup type to one of the
 351         other values above.  To do this, run tao_nt_cosnotification -t n, where
 352         n is a number corresponding to one of the startup modes listed above.
 353
 354         In order to debug the service's execution itself, use the -d
 355         option.