TAO/tests/CSD_Strategy_Tests/TP_Test_4/README

   1
   2 ===========================================================================
   3 Directory: $TAO_ROOT/tests/CSD_Strategy_Tests/TP_Test_4
   4
   5 Uses Libs: $TAO_ROOT/tests/CSD_Strategy_Tests/TP_Test_Lib
   6            $TAO_ROOT/tests/CSD_Strategy_Tests/TP_Foo_C
   7
   8 ===========================================================================
   9 Executable: server_main
  10
  11 Description: The test server application.
  12
  13 Command-Line:
  14
  15       % server_main [options]
  16
  17       where, [options] includes the following:
  18
  19             -p <ior_filename_prefix>
  20             -s <num_servants>
  21             -n <num_csd_threads>
  22             -t <num_orb_threads>
  23             -r <num_remote_clients>
  24             -c <num_collocated_clients>
  25             -k <collocated_client_kind>
  26             -?
  27
  28 Command-Line Arguments:
  29
  30     -p <ior_filename_prefix>
  31
  32         If not specified, the <ior_filename_prefix> defaults to "foo".
  33         This value is used as the prefix for the filename(s) to which
  34         the server application will write stringified object reference(s).
  35         Each "IOR file" contains the (stringified) object reference
  36         associated with a distinct servant object within the server
  37         application.  These files are the way that the client application(s)
  38         are able to "locate" the object reference(s) upon which they will
  39         invoke (CORBA) operations.  In essence, the filesystem is used
  40         as a "poor-man" Naming Service.
  41
  42         The filenames are of the form, "prefix_%02d.ior", using a unique
  43         integer "id" for each file - starting with an "id" of 1.  Thus,
  44         if the server application was told to create 3 servants (via the
  45         -s <num_servants> option), and the <ior_filename_prefix> is "foo",
  46         then three files will be written by the server application:
  47
  48                 foo_01.ior
  49                 foo_02.ior
  50                 foo_03.ior
  51
  52
  53     -s <num_servants>
  54
  55         The <num_servants> must be an integer value greater than 0.
  56
  57         If not specified, the <num_servants> defaults to 1.  This is used
  58         to inform the server application of the number of distinct servant
  59         objects that it should create.
  60
  61
  62     -n <num_csd_threads>
  63
  64         The <num_csd_threads> must be an integer value greater than 0.
  65
  66         If not specified, the <num_csd_threads> defaults to 1.  This is
  67         used to inform the server application of the number of worker
  68         threads that should be activated by the Thread Pool CSD Strategy.
  69         The worker threads are responsible for servicing the strategy's
  70         request queue.  This can also be called the "size of the thread
  71         pool".
  72
  73
  74     -t <num_orb_threads>
  75
  76         The <num_orb_threads> must be an integer value greater than 0.
  77
  78         If not specified, the <num_orb_threads> defaults to 1.  This option
  79         is used to tell the server application how many distinct threads
  80         should be used to run the ORB event loop.  The "mainline thread"
  81         will always run the ORB event loop itself, so that accounts for
  82         one of the num_orb_threads.  If num_orb_threads is greater than 1,
  83         then (num_orb_threads - 1) threads will be activated by the server
  84         application, and each of these threads will run the ORB event loop.
  85         The end result is that there will be <num_orb_threads> distinct
  86         threads (including the mainline thread) running the ORB event loop.
  87
  88
  89     -r <num_remote_clients>
  90
  91         The <num_remote_clients> must be an integer value greater than,
  92         or equal to, 0.  In addition, the sum of the <num_remote_clients>
  93         and the <num_collocated_clients> (see the -c option) must be
  94         greater than 0.  Both cannot be 0, since the server application
  95         would interpret this to mean that no clients will ever use it,
  96         and that's kind of pointless.
  97
  98         If not specified, the <num_remote_clients> defaults to 1.  This
  99         option informs the server application how many remote clients it
 100         can expect to "hear" from over the course of its lifetime.  Each
 101         distinct test client, remote or collocated, is required to invoke
 102         the done() operation on one of the servant objects.  The server
 103         application decides to shut itself down gracefully when it has
 104         received one done() invocation for each remote client and for
 105         each collocated client.  Once all of the expected done() calls
 106         have been made, the server application assumes that no more clients
 107         will need its services, and thus it shuts itself down.  This is
 108         used to support the automated test scenarios implemented within
 109         the run_test.pl script.  It provides a way for a test scenario to
 110         automate the graceful shutdown of the server by telling the server
 111         how many clients to expect (remote + collocated).
 112
 113
 114     -c <num_collocated_clients>
 115
 116         The <num_collocated_clients> must be an integer value greater than,
 117         or equal to, 0.  In addition, the sum of the <num_collocated_clients>
 118         and the <num_remote_clients> (see the -r option) must be
 119         greater than 0.  Both cannot be 0, since the server application
 120         would interpret this to mean that no clients will ever use it,
 121         and that's kind of pointless.
 122
 123         If not specified, the <num_collocated_clients> defaults to 0.  This
 124         option informs the server application how many collocated clients
 125         should "live", collocated, within the server application.  Each
 126         collocated client will execute its logic in a distinct thread
 127         within the server application.  As an example, if the server
 128         application was told to use a <num_collocated_clients> value of 40,
 129         then the server application will activate 40 threads - each
 130         carrying out the logic of one "client".  This client "logic" is
 131         identical to the logic carried out by a single remote client
 132         application (client_main) process.  As with remote clients,
 133         each collocated client will invoke the done() operation on
 134         one of the servants (via an object ref) when the client logic
 135         has been completed.  See the "-r <num_remote_clients>" option
 136         for more information about the done() operation, and its purpose.
 137
 138         For this particular server application (TP_Test_4), each
 139         collocated client will perform the normal client logic as well
 140         as carry out a set of "custom" requests on the collocated servant.
 141         Custom operations not defined in IDL.
 142
 143
 144     -k <collocated_client_kind>
 145
 146         This is reserved for future use.  It currently doesn't get used
 147         for anything.
 148
 149
 150     -?
 151
 152         This is used to request the "Usage Statement" for the Server
 153         Application (ie, "server_main -?" prints the usage statement).
 154
 155
 156 ===========================================================================
 157 Executable: client_main
 158
 159 Description: The test client application.
 160
 161 Command-Line:
 162
 163       % client_main [options]
 164
 165       where, [options] includes the following:
 166
 167             -i <ior>
 168             -n <client_id>
 169             -k <collocated_client_kind>
 170             -?
 171
 172
 173 Command-Line Arguments:
 174
 175     -i <ior>
 176
 177         The <ior> is required, and must be a valid IOR.  In our case, where
 178         the server application saves stringified object references to files,
 179         we supply the client application with an <ior> in the following
 180         form: "file://foo_01.ior".  See the server application's description
 181         of its "-p <ior_filename_prefix>" option for more information.
 182
 183         The client application will use the <ior> to obtain an object
 184         reference using the CORBA::ORB::string_to_object() method.  This
 185         is the object reference upon which the client logic will invoke
 186         operations.  The object reference will be associated with a
 187         distinct servant object within the server application.
 188
 189
 190     -n <client_id>
 191
 192         The <client_id> is required, and must be an integer value greater
 193         than 0.
 194
 195         As part of the logic used to check actual vs. expected results,
 196         each client is assigned a unique id.  As a side-note, each
 197         collocated client within the server application (if there are
 198         any) will also be assigned a unique client_id.  For any given
 199         test scenario run by the run_test.pl script, each client (remote
 200         and/or collocated) will be assigned a unique client_id.
 201
 202         The server application assigns client_ids to its collocated clients
 203         based upon its knowledge of how many remote clients will be used
 204         in the test scenario (see the "-r <num_remote_clients>" option
 205         for the server application).  The server application assumes that
 206         the run_test.pl will assign client_ids to remote clients starting
 207         with 1, and up to the <num_remote_clients>.  Thus, the server
 208         application assigns client_ids to collocated clients starting
 209         with (<num_remote_clients> + 1), and incrementing by 1 for each
 210         additional collocated client_id.
 211
 212
 213     -k <collocated_client_kind>
 214
 215         This is reserved for future use.  It currently doesn't get used
 216         for anything.
 217
 218
 219     -?
 220
 221         This is used to request the "Usage Statement" for the Client
 222         Application (ie, "client_main -?" prints the usage statement).
 223
 224
 225 ===========================================================================
 226 Executable: run_test.pl (PERL script).
 227
 228 Description: Script used to run a specific test scenario.  This includes
 229              the launching of a server application process and client
 230              applications processes as called for by the specific scenario.
 231
 232 Command-Line:
 233
 234       % run_test.pl <scenario>
 235
 236       where, <scenario> can be one of the following values:
 237
 238             "big"
 239             "a"
 240             "b"
 241
 242       If a <scenario> is not specified on the run_test.pl command-line,
 243       then a default scenario is used.
 244
 245
 246 Scenarios:
 247
 248     -----------------------------------------------------------------------
 249     Default: (when no <scenario> is specified on the command-line)
 250
 251         $iorfname_prefix        = "servant";
 252         $num_servants           = 1;
 253         $num_orb_threads        = 1;
 254         $num_remote_clients     = 1;
 255         $num_csd_threads        = 1;
 256         $num_collocated_clients = 0;
 257
 258     -----------------------------------------------------------------------
 259     "remote":
 260
 261         Uses the Default values, with the following overrides:
 262
 263             $num_remote_clients = 40;
 264
 265     -----------------------------------------------------------------------
 266     "collocated":
 267
 268         Uses the Default values, with the following overrides:
 269
 270             $num_remote_clients = 0;
 271             $num_collocated_clients = 1;
 272
 273     -----------------------------------------------------------------------
 274     "collocated_big":
 275
 276         Uses the Default values, with the following overrides:
 277
 278             $num_remote_clients = 0;
 279             $num_csd_threads = 5;
 280             $num_collocated_clients = 40;
 281
 282     -----------------------------------------------------------------------
 283     "remote_orbthreads":
 284
 285         Uses the Default values, with the following overrides:
 286
 287             $num_orb_threads = 5;
 288             $num_remote_clients = 40;
 289
 290     -----------------------------------------------------------------------
 291     "remote_servants":
 292
 293         Uses the Default values, with the following overrides:
 294
 295             $num_servants = 5;
 296             $num_remote_clients = 40;
 297
 298     -----------------------------------------------------------------------
 299     "remote_csdthreads":
 300
 301         Uses the Default values, with the following overrides:
 302
 303             $num_csd_threads = 5;
 304             $num_remote_clients = 40;
 305
 306     -----------------------------------------------------------------------
 307     "remote_big":
 308
 309         Uses the Default values, with the following overrides:
 310
 311             $num_csd_threads = 5;
 312             $num_servants = 10;
 313             $num_orb_threads = 4;
 314             $num_remote_clients = 40;
 315
 316     -----------------------------------------------------------------------
 317     "big":
 318
 319         Uses the Default values, with the following overrides:
 320
 321             $num_csd_threads = 5;
 322             $num_servants = 10;
 323             $num_orb_threads = 4;
 324             $num_remote_clients = 40;
 325             $num_collocated_clients = 40;
 326
 327     -----------------------------------------------------------------------
 328     "usage":
 329
 330         This is not really a test scenario, but it will cause the
 331         run_test.pl script to print a "Usage Statement", which includes
 332         a list of the supported <scenario> values.
 333
 334     -----------------------------------------------------------------------
 335
 336
 337 ===========================================================================