// $Id$

CONTENT:

INTRO
SOURCE FILES
SERVICE DESCRIPTION
EXAMPLE DESCRIPTION
HOW TO RUN
COMMAND-LINE OPTIONS


INTRO

This directory contains: 1) definition and implementation of a simple
CORBA Load Balancing Service and 2) client and server illustrating the
use of this service.


SOURCE FILES

Load_Balancer.idl
Load_Balancer_i.h
Load_Balancer_i.cpp:
                      Load Balancing Service interface and its
                      implementation.

Load_Balancing_Service.h
Load_Balancing_Service.cpp:
                      Load Balancing Service driver.

Identity.idl
Identity_i.h
Identity_i.cpp:
                     Interface and implementation of a simple CORBA
                     object used in the client-server example.

Identity_Server.cpp
Identity_Client.cpp:
                    Client and server example, illustrating the use of the
                    Load Balancing Service.


SERVICE DESCRIPTION

For interface and detailed description see Load_Balancer.idl.  Two
load balancing protocols are supported: random and round-robin.
Servers register their objects with either random or round robin
object groups, and clients request object references from those groups.

This is a very basic approach to load balancing: there is no feedback
mechanism to allow registered servers to notify Load Balancing service of
how busy they are.  Also, the use of the service is not transparent to
client applications.

The service can be used in different ways.  Depending
on the system and its characteristics, it might make more sense for a
client to either 1) obtain a new object reference from the Load
Balancing service for each invocation or 2) obtain new references from
the Load Balancing service at certain intervals, measured in time or
number calls or 3) use the Load Balancing service just once, to obtain
the initial object reference.

Related material:

      - Persistent version of this Load Balancing Service can be found
        in TAO/examples/Load_Balancing_persistent.

      - TAO's Load Balancing Service (definition, implementation and
        tests are located in TAO/orbsvcs tree) This is a more
        sophisticated Load Balancing implementation, which is
        distributed as one of TAO's Object Services.


EXAMPLE DESCRIPTION

Simple client and server are provided to illustrate the use of the
Load Balancing service (LB).  The server creates two object groups in
the LB, one random and one round robin.  It then creates the specified
number of <Identity> objects and registers them with the random object
group in LB.  Same is done with the round robin group.  The client
performs the specified number of invocation on <Identity> object,
contacting the specified group of LB for a new object reference before
each invocation.

HOW TO RUN

run_test.pl perl script can be used to run the example, i.e., the Load
Balancing service, the server and the client.  (The output from the
perl script is somewhat confusing since it is a mixture of output from
client, server and load balancing service.)  Alternatively, the
example (or just the load balancing service) can be started manually.

First, start the Load Balancing service, specifying the file where to
store its ior.  Then start the server, and, finally, the client, as
shown below. Run each executable in its own window for output readability.
Command-line options are described in the next section.

$ load_balancer -o balancer.ior
$ server -i file://balancer.ior
$ client -i file://balancer.ior


COMMAND LINE OPTIONS

Load_Balancing Service:

 -d
                increase debug output
 -o <file_name>
                output file for the <Object_Group_Factory> ior


Server:

 -d
                increase debug output
 -i <ior>
                ior of the <Object_Group_Factory> object
 -a <number>
                number of objects to create/register with the random
                group (default value is 5)
 -o <number>
                number of objects to create/register with the round
                robin group (default value is 5))


Client:

 -d
                increase debug output
 -i <ior>
                ior of the <Object_Group_Factory> object
 -n <number>
                number of times to make invocation on Identity object
                (default value is 5)
 -r
                use random group for obtaining references (as opposed
                to the round robin group) (default value is use round robin)