Connection Purging Test       By: Kirthika Parameswaran <kirthika@cs.wustl.edu>            
=======================           Irfan Pyarali <irfan@cs.wustl.edu>

This is a test which stress tests the connection management and checks
whether cached handlers are purged effectively when the process runs
out of descriptors.

Connection Caching Feature
--------------------------

Motivation:

In TAO, open connections are stored in a connection cache and reused
for the subsequent requests between the same client and server.  This
is done to avoid the cost of establishing new connections. Every
connection needs a OS handle which has to obtained from the OS. The OS
can allot only a fixed number of handles to a process.  This can
become a issue in case of clients and servers with multiple handles
open who may not be allowed to establish a new connection as the
process has run out of handles.

Aim:

Clients and servers should be able to to continue making new
connections by tearing down "old" connections.

Solution: Auto-purging

The connections are stored in a cache. When ever the connect call
fails due to the process running out of handles, auto-purging will
kick in and some "old" connections will be removed from the connection
cache.  The decision about which connections are "old" is made by the
caching strategies. The percentage of existing connections to be
purged is controlled by a purge percent.

ACE classes: Caching_Utility, Cleanup_Stratgies, and
Caching_Strategies have been used.  Simple examples are available in
$ACE_ROOT/tests/Cached_Accept_Conn_Test.cpp and
$ACE_ROOT/tests/Cached_Conn_Test.cpp.

Note that the users can also purge handles used by the ORB explicitly
through TAO_Connector_Registry::purge_connections().  This can enable
them to open new handles for their application.

Test:
----

This test creates the number of "server" ORBs specified by the -i
option and has a client ORB which invokes remote methods on these
ORBs.

Two possible cases:

1. When the process runs out of handles during "connect", the
Connector removes handlers from its connection cache depending upon
the kind of connection caching strategy followed. (by default: Least
Recently Used) set by the ORBConnectionCachingStrategy option.

Its expected to see an exception when the handle limit is surpassed.
The cached handles are then used and the test continues displaying 
how scalability was increased using caching of connection handles.

2. When the "accept" or "open" calls made by the Acceptors in the same
process fail, request is made on all the Connectors of all the ORBs in
the system to perform purging depending on the ORBPurgePercentage
value provided.

Note: This test does not use the Collocation optimisations since we
want to use up handles and test the connection caching as well as
purging.

Options:
-------

i:  Number of iteration which equals the number of server orbs.

d:  Debugging ON 

a:  Number of handles to be kept free. The Handle Gobbler will
   eat up the max_handles specified for the OS but leave
   behind the handles requested. This helps in testing more
   effectively. Please remember to set this value judiciously.

r:  Number of remote call invocations to be made by the client
   on the servant.

?:  help!


Options Using  svc.conf:
-----------------------

Through options to the Resource_Factory :-
-ORBConnectionCachingStrategy <lru/lfu/fifo/null>
-ORBPurgePercent <percentage>

Execution:
---------

Simply run the ./run_test.pl !

else

./Connection_Purging -ORBCollocation no 

with options specified per need.    


