/** -*- HTML-Helper -*-
@mainpage Implementation Repository
@section intro Introduction
The purpose of the Implementation Repository (ImR) in TAO is for the automatic
activation of a TAO server when a method is invoked but the server is not
running. It does this by working with the server to keep track of when it is
activated and stores information on how to reactivate it. Method
invocations on the server will actually be sent to the Implementation
Repository, which will then be able to start the server process if it is not
already running and forward the invocation to the real server.
@section resources Resources
The ImR in TAO was first based on a paper on the subject by
Michi Henning
called Binding,
Migration, and Scalability in CORBA. Mr. Henning later went on to
coauthor the book
Advanced CORBA Programming in C++ and included a chapter on the
Implementation Repository. The description of the ImR in this chapter is used
as the specification for TAO's ImR.
@ref usersguide - Overall documentation on how to use the ImR in your programs
@ref ntservice - Running the ImR as a NT Service
@ref imrandnaming - Using the Naming Service with the Implementation Repository
@section authors Authors
The guy who first worked on ImR and provided a base for the current
ImR is Darrell Brunsch
@<brunsch@cs.wustl.edu@>.
The current version is developed by Phil Mesnier
@<mesnier_p@ociweb.com@>.
You can reach us by either email (which is better), or through the
ACE mailing list
@<ace-users@list.isis.vanderbilt.edu@>.
If you use the mailing list, it is required to join it before sending
a question since responses are usually just replied back to the group.
The NT Service part of the ImR was developed by Jeff Parsons @<parsons@cs.wustl.edu@>. He can
also be reached via the same channels.
It was later extended and enhanced by Justin Michel
*/
/**
@page usersguide Implementation Repository User's Guide
In order for a server to make use of the Implementation Repository, it must
communicate with the ImR to keep it up to date on such things as the server's
running status. These functions now are contained within the POA, so when a
Persistent POA is used on a server that has -ORBUseImR specified, it will
communicate with an Implementation Repository, if one is available.
@subsection description The ImR
The ImR is based on the ImR in TAO 1.2.2 with added features to help
improve throughput and load balancing. The work to be performed by the
Implementation Repository is distributed between two entities (locator
and activator) to help achieve the goal of better throughput and load
balance.
@subsection locator tao_imr_locator
The locator acts as the main server which is visible to the
application intending to use the ImR. It receives requests sent via
tao_imr and distributes the work to the registered activators. It is
stateless and does not maintain any information except about the
activators that are registered with it. Its job is to act as a
mediator between the application and the actual activator that does
the real work. As of now, we only support one locator to be running at
any time. locator can be reached through the usual methods of
-ORBInitRef and -ORBDefaultInitRef and multicast.
Commandline Arguments that can be passed to tao_imr_locator
-d locator specific debug level
-m support multicast discovery.
-l lock the repository, making it read only.
-o write the ior to the file.
-t specify a startup timeout value (default 60 seconds)
-i periodically ping servers to check liveness.
-v the minimum successful ping interval. (default 10 seconds)
-g the timeout for ping attempts. (default 1 second)
-s run as a winNT service
-c execute the named service command: install, remove
-x support persistence to the locator. We use XML to support
persistence. Names of the activators registered with the locator,
their IORs, and the servers registered with each of the activators are
saved to the xml file. Use this option to pass the name of the file
where the data has to be saved.
-p similar to "-x" but using an ACE_Configuration_Heap file to persist
the data.
-r similar to "-p" but using an ACE_Configuration_Win32Registry to persist
the data. (only available on Win32 platforms)
--directory similar to "-x" option, but the repository will be written out
to multiple files in the indicated directory: "imr_listings.xml" which
indicates all servers and activators in the repository indicating the
filename containing that server's or activator's persistence data.
This option is used along with the "--primary" or "--backup" option
to create a Fault Tolerant locator.
--primary pass along with "--directory " to startup the primary
ImR_Locator. See ft_imr_locator subsection.
--backup pass along with "--directory " to startup the backup
ImR_Locator. See ft_imr_locator subsection.
-UnregisterIfAddressReused Enable the verification that a newly started server is reusing
the endpoint address of another server that it is not linked with. If it
finds this case, and the existing server is not running, its registration
is removed.
And, of course, the ORB Options.
@subsection ft_imr_locator FaultTolerant_ImR_Locator
The ImR_Locator implements a fault tolerant service with the following options:
The --primary option tells the ImR_Locator that it will startup as the primary
in a redundant service pair.
The --backup option tells the ImR_Locator that it will startup as the backup
in a redundant service pair.
The --directory option tells the ImR_Locator the shared
file system directory to use as the backing store for the redundant service
pair.
The -o option tells the ImR_Locator to output the
redundant service pair ImRService ior file, which it can only do after
successfully starting the primary and backup ImRService instances. The ior
file contains the combined profiles of the primary and backup ImRLocators. The
client must use the ior file to use the fault tolerant locator.
The primary and backup ImRLocator instances should have the same ORBEndPoint
protocol list so that any client can send a request to either primary or backup
regardless of protocol (IIOP,UIOP,etc...).
The ImR_Locator primary and backup options cannot be passed on the command
line along with -ORBObjRefStyle URL, since that style will cause the backup
profile to not be available in the ior.
At startup the primary must be started first, then the backup. When
a single ImR_Locator goes down, it can be restarted at anytime
(using the same ORBEndPoints). If they are both shutdown after a successful
startup of the redundant pair, then either the primary or backup can be
restarted first. With only a single server running, there is no fault
tolerance support, but the original fault tolerant ior which was created
by the backup with the -o option can still be used as long as the ORBEndPoint
list remains the same for both instances.
As long as both the primary and backup ImR_Locators are not shutdown at the
same time the Fault Tolerant locator will always be available.
@subsection ft_imr_locator_startup FaultTolerant_ImR_Locator Startup
Start the primary.
It will write the replication ior to a file in the shared persistence
directory.
tao_imr_locator
--primary
-ORBEndpoint
--directory
Start the backup.
Reads the primary replication ior from the shared persistence directory.
Writes the multi-profile ior to ft_imr_ior_filename .
tao_imr_locator
--backup
-ORBEndpoint
--directory
-o
@subsection activator tao_imr_activator
Activators, as you might have guessed, do the real work of
activating servers or shutting them down and maintaining the information
about servers related to them. Only one instance of an activator
can be run on one host. The activator is not exposed at all to the
application. Only the locator needs to and it is the only one that
can contact the activator.
An instance of tao_imr_activator first registers itself with the
locator so that it can begin to receive requests. When registering
with the locator, it passes the hostname where it is being run and
its IOR to the locator. And, the locator reaches it using the
same information.
The Commandline parameters that are valid for tao_imr_activator are
-c Run the Service command: install, remove, install_no_imr
-d Debug Information
-l Notify the locator of server state changes
-o Write the IOR to a file
-s Run as a winNT service.
-e Supply an Environment buffer length
-m Supply a max number of Environment variables
-delay