TAO/docs/transport_current/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2
   3 <!--  -->
   4
   5 <HTML>
   6 <HEAD>
   7 <TITLE>Using the TAO::Transport::Current Feature</TITLE>
   8
   9 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  10 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  11
  12 <LINK REL="STYLESHEET" HREF="transport_current.css">
  13
  14 </HEAD>
  15
  16 <BODY TEXT = "#000000" LINK="#000fff" VLINK="#ff0f0f" BGCOLOR="#ffffff">
  17
  18 <P>
  19
  20 <H1 ALIGN="CENTER">Using the TAO::Transport::Current Feature</H1>
  21
  22
  23 <P ALIGN="CENTER">
  24 Object Computing Inc.<BR>
  25 St.Louis, Missouri
  26 </P>
  27
  28 <P ALIGN="CENTER">
  29 <SMALL><STRONG>
  30 <A HREF="mailto:iliyan@ociweb.com">Iliyan Jeliazkov</A>
  31 <A HREF="mailto:mesnier_p@ociweb.com">Phil Mesnier</A>
  32  and <A HREF="mailto:<john_c@ociweb.com">Ciju John</A>
  33 </STRONG></SMALL>
  34 </P>
  35
  36 <HR>
  37
  38 <P>
  39 <H3>Scope and Context</H3><P>
  40
  41 <P>In TAO, it is just too hard to obtain statistical or pretty much any operational information about the network transport which the ORB is using. While this is a direct corollary of the CORBA's design paradigm which mandates hiding all this hairy stuff behind non-transparent abstractions, it also precludes effective ORB and network monitoring.
  42 </P>
  43
  44 <P>
  45 The Transport::Current feature intends to fill this gap by defining a
  46 framework for developing a wide range of solutions to this problem. It also provides a basic implementation for the most common case - the IIOP transport.
  47 </P>
  48
  49 <P>
  50 By definition, transport-specific information is available in
  51 contexts where the ORB has selected a Transport:</P>
  52
  53 <UL>
  54   <LI>Within Client-side interception points;</LI>
  55   <LI>Within Server-side interception points;</LI>
  56   <LI>Inside a Servant up-call</LI>
  57 </UL>
  58
  59 <P>
  60 The implementation is based on a generic service-oriented
  61 framework, implementing the TAO::Transport::Current interface. It is
  62 an optional service, which can be dynamically loaded. This service makes
  63 the Transport::Current interface available through
  64 orb->resolve_initial_references() . The basic idea is that whenever a Transport is
  65 chosen by the ORB, the Transport::Current (or a derivative) will have access
  66 to that instance and be able to provide some useful information.
  67 </P>
  68
  69 <BR><HR>
  70
  71
  72 <P>
  73 <H3>
  74 Programmer's Reference
  75 </H3>
  76
  77 <P>
  78 Consider the following IDL interface, describing a Factory for
  79 producing TAO::Transport::Traits instance, which represents
  80 transport-specific data.
  81 </P>
  82
  83 <PRE>
  84 #include <IOP.pidl>
  85 #include <TimeBase.pidl>
  86
  87 module TAO
  88 {
  89   /// A type used to represent counters
  90   typedef unsigned long long CounterT;
  91
  92   module Transport
  93   {
  94     /// Used to signal that a call was made within improper invocation
  95     /// context.  Also, this exception is thrown if no Transport has
  96     /// been selected for the current thread, for example in a
  97     /// collocated invocation.
  98
  99     exception NoContext
 100     {
 101     };
 102
 103     // The primary interface, providing access to Transport
 104     // information, available to the current thread.
 105
 106     local interface Current
 107     {
 108       /// Transport ID, unique within the process.
 109       readonly attribute long id raises (NoContext);
 110
 111       /// Bytes sent/received through the transport.
 112       readonly attribute CounterT bytes_sent raises (NoContext);
 113       readonly attribute CounterT bytes_received raises (NoContext);
 114
 115       /// Messages (requests and replies) sent/received using the current
 116       /// protocol.
 117       readonly attribute CounterT messages_sent raises (NoContext);
 118       readonly attribute CounterT messages_received raises (NoContext);
 119
 120       /// The absolute time (miliseconds) since the transport has been
 121       /// open.
 122       readonly attribute TimeBase::TimeT open_since raises (NoContext);
 123     };
 124   };
 125 };
 126 </PRE>
 127
 128 <P>
 129 As an example of a specialized Transport::Current is the Transport::IIOP::Current, which derives from Transport::Current and has an interface, described in the following IDL:
 130 </P>
 131
 132 <PRE>
 133 #include "TC.idl"
 134
 135 /// Provide a forward reference for the SSLIOP::Current
 136 module SSLIOP
 137 {
 138   interface Current;
 139 };
 140
 141
 142 module TAO
 143 {
 144   module Transport
 145   {
 146     module IIOP
 147     {
 148       // The primary interface, providing access to IIOP-specific
 149       // transport information, if it is indeed an IIOP (-like) transport
 150       // that has been selected.
 151
 152       local interface Current : TAO::Transport::Current
 153       {
 154         /// Remote host
 155         readonly attribute string remote_host raises (NoContext);
 156
 157         /// Remote port Using long (signed) type to better accomodate
 158         /// the Java mapping, which has no support for unsigned values
 159         readonly attribute long remote_port raises (NoContext);
 160
 161         /// Local host
 162         readonly attribute string local_host raises (NoContext);
 163
 164         /// Local port
 165         readonly attribute long local_port raises (NoContext);
 166
 167         /// If this is a "secure" transport, this method will give you
 168         /// the corresponding SSLIOP::Current
 169         readonly attribute ::SSLIOP::Current ssliop_current raises (NoContext);
 170       };
 171     };
 172   };
 173 };
 174 </PRE>
 175
 176
 177 <P>
 178 <H3>
 179 User's Guide
 180 </H3>
 181
 182 <P>
 183 The TAO::Transport::Current can be used as a base interface for a more specialized TAO::Transport::X::Current. It is not required, however that a more specialized Current inherits from it.
 184 </P>
 185
 186 <P>
 187 Typical, generic usage is shown in the
 188 $TAO_ROOT/orbsvcs/tests/Transport_Current/Framework test:
 189 </P>
 190
 191 <PRE>
 192 ...
 193   // Get the Current object.
 194   ::CORBA::Object_var tcobject =
 195     orb->resolve_initial_references ("TAO::Transport::Current"
 196                                       ACE_ENV_SINGLE_ARG_DECL);
 197   ACE_TRY_CHECK;
 198
 199   ::TAO::Transport::Current_var tc =
 200       ::TAO::Transport::Current::_narrow (tcobject.in ()
 201                                       ACE_ENV_SINGLE_ARG_DECL);
 202   ACE_TRY_CHECK;
 203
 204   if (CORBA::is_nil (tc.in ()))
 205     {
 206       ACE_ERROR ((LM_ERROR,
 207                   ACE_TEXT ("(%P|%t) client - ERROR: Could not resolve ")
 208                   ACE_TEXT ("TAO::Transport::Current object.\n")));
 209
 210       ACE_TRY_THROW (CORBA::INTERNAL ());
 211     }
 212 ...
 213 </PRE>
 214
 215 <P>
 216 Another example is available from the $TAO_ROOT/orbsvcs/tests/Transport_Current/IIOP test. This fragment shows how to obtain transport-specific information:
 217 </P>
 218
 219 <PRE>
 220 ...
 221    // Get the specific Current object.
 222   CORBA::Object_var tcobject =
 223     orb->resolve_initial_references (ACE_TEXT_ALWAYS_CHAR ("TAO::Transport::IIOP::Current")
 224                                      ACE_ENV_ARG_PARAMETER);
 225   ACE_TRY_CHECK;
 226
 227
 228   Transport::IIOP::Current_var tc =
 229     Transport::IIOP::Current::_narrow (tcobject.in ()
 230                                        ACE_ENV_SINGLE_ARG_DECL);
 231   ACE_TRY_CHECK;
 232
 233   if (CORBA::is_nil (tc.in ()))
 234       ACE_TRY_THROW (CORBA::INTERNAL ());
 235
 236   ::CORBA::String_var rhost (tc->remote_host (ACE_ENV_SINGLE_ARG_PARAMETER));
 237   ACE_TRY_CHECK;
 238
 239   ::CORBA::String_var lhost (tc->local_host (ACE_ENV_SINGLE_ARG_PARAMETER));
 240   ACE_TRY_CHECK;
 241
 242   ::CORBA::Long id = tc->id (ACE_ENV_SINGLE_ARG_PARAMETER);
 243   ACE_TRY_CHECK;
 244
 245   ::TAO::CounterT bs = tc->bytes_sent (ACE_ENV_SINGLE_ARG_PARAMETER);
 246   ACE_TRY_CHECK;
 247
 248   ::TAO::CounterT br = tc->bytes_received (ACE_ENV_SINGLE_ARG_PARAMETER);
 249   ACE_TRY_CHECK;
 250
 251   ::TAO::CounterT rs = tc->messages_sent (ACE_ENV_SINGLE_ARG_PARAMETER);
 252   ACE_TRY_CHECK;
 253
 254   ::TAO::CounterT rr = tc->messages_received (ACE_ENV_SINGLE_ARG_PARAMETER);
 255   ACE_TRY_CHECK;
 256 ...
 257 </PRE>
 258
 259
 260
 261 <P>
 262 <H3>
 263 Configuration, Bootstrap, Initialization and Operation
 264 </H3>
 265
 266 <P>
 267 To use the Transport Current features the framework must be loaded
 268 through the Service Configuration framework. For example, using
 269 something like this:
 270 </P>
 271
 272 <PRE>
 273 dynamic TAO_Transport_Current_Loader Service_Object * TAO_TC:_make_TAO_Transport_Current_Loader() ""
 274 </PRE>
 275
 276 <P>
 277 The Transport_Current_Loader service uses an ORB initializer to register the "TAO::Transport::Current" name in a way that allows it to be resolved via orb->resolve_initial_references(). The implementation is the TAO::Transport::Current_Impl class.
 278 </P>
 279
 280 <P>
 281 A transport-specific Traits_Factory objects are loaded like this:
 282 </P>
 283
 284 <PRE>
 285 ...
 286 dynamic TAO_Transport_IIOP_Current_Loader Service_Object * TAO_TC_IIOP:_make_TAO_Transport_IIOP_Current_Loader() ""
 287 ...
 288 </PRE>
 289
 290 <P>
 291 Note that any number of transport-specific Current interfaces may be available at any one time.
 292 </P>
 293
 294 <P>
 295 Whenever a Transport::Current method is invoked, a pointer to the currently selected Transport instance must be accessible through Thread Specific Storage (TSS). For each thread, this is managed by modifying the TAO classes, instances of which are created on the stack during request/response processing.
 296 </P>
 297
 298 <P>
 299 <H3>
 300 Implementation and Required Changes
 301 </H3>
 302
 303 <P>
 304 The primary implementation is predicated upon usage of thread specific
 305 storage (TSS) and the guarantees C++ provides for calling the
 306 constructor and the destructor of automatic (stack-based)
 307 objects. Some existing objects, used in TAO will have to be modified
 308 and the necessary changes, both for client and the server side are
 309 detailed below.
 310 </P>
 311
 312 <H4>
 313 Client Side: Sending Requests or Replies
 314 </H4>
 315
 316
 317 <P>
 318 The Profile_Transport_Resolver instance contains the reference to the
 319 Transport, which is the TAO implementation structure that is needed to extract
 320 any protocol-specific information. An
 321 instance of Profile_Transport_Resolver lives on the stack, starting
 322 inside a call to Invocation_Adapter::invoke_remote_i(), or
 323 LocateRequest_Invocation_Adapter::invoke(). In the case of collocated
 324 invocations no such object is created.
 325 </P>
 326
 327 <P>
 328 It is then passed around the calls that follow, except for the calls
 329 to the following Invocation_Base methods: send_request_interception(),
 330 receive_other_interception(), receive_reply_interception(),
 331 handle_any_exception(), handle_all_exception();
 332 </P>
 333
 334 <P>
 335 Note that these in turn call the client-side interception points and
 336 that is where information about the transport will be needed. In order
 337 to make the transport information accessible inside those methods, we
 338 changed Profile_Transport_Resolver and the TAO_ServerRequest classes to
 339  incorporate an additional member:
 340 </P>
 341
 342 <PRE>
 343 ...
 344 TAO::Transport_Selection_Guard transport_;
 345 ...
 346 </PRE>
 347
 348
 349 <P>
 350 This guard automatically keeps track of the currenty selected Transport from within its constructor and destructor. The rest of the TC framework  makes sure this pointer is stored in a thread-specific storage, by adding an additional member to TSS_Resources:
 351 </P>
 352
 353 <PRE>
 354 ...
 355 TAO::Transport_Selection_Guard* tsg_;
 356 ...
 357 </PRE>
 358
 359 <P>
 360 The idea is to keep a pointer to the last guard on the current thread. Each guard keeps a pointer to the previous, effectively creating a stack of transport selection guards. The stack structure ensures both that the selection/deselection of a Transport will be correctly handled. It also ensures that, in case the current thread temporarily changes the Transport, the previous “current” transport will be preserved, no matter how many times such change occurs. A good example for this is a nested up-call scenario.
 361 </P>
 362
 363 <P>
 364 Inside an interceptor, one can use the methods from Transport Current to obtain information on the currently selected transport. The implementation simply looks up the TAO_Transport pointer via TSS_Resources::tsg_ and obtains the requested data.
 365 </P>
 366
 367
 368
 369 <H4>
 370 Server Side: Request Processing
 371 </H4>
 372
 373
 374 <P>
 375 On the server side, the TAO_ServerRequest instance already has a
 376 Transport pointer. The TAO_ServerRequest lives on the stack, starting
 377 its life inside a call to TAO_GIOP_Message_Base::process_request().
 378 </P>
 379
 380 <P>
 381 Similarly to the client-side, we changed the TAO_ServerRequest
 382 to add a field:
 383 </P>
 384
 385 <PRE>
 386 ...
 387 TAO::Transport_Selection_Guard transport_;
 388 ...
 389 </PRE>
 390
 391 <P>
 392 Operation is similar to the client-side case. In the collocated case there may not be a
 393 transport available, so the TSS slot will be null.
 394 </P>
 395
 396 <P>
 397 Inside an interceptor then, one can use an RIR-resolved
 398 TransportCurrent to create a specialization of TransportInfo, based on
 399 the kind of Transport used. Then they would _downcast() it to the
 400 specific type.
 401 </P>
 402
 403 <H3>
 404 Structural and Footprint Impact
 405 </H3>
 406
 407 <P>
 408 As the IIOP implementation of the Transport Current functionality requires additional
 409 data to be kept about the Transport, we added a new field to TAO_Transport:
 410 </P>
 411
 412 <PRE>
 413 ...
 414   /// Transport statistics
 415   TAO::Transport::Stats* stats_
 416 ...
 417 </PRE>
 418
 419 <P>
 420 TAO::Transport::Stats is a simple structure, which keeps track of useful statistical
 421 information about how a transport is used:
 422 </P>
 423
 424 <PRE>
 425 ...
 426     class TAO_Export Stats
 427     {
 428     public:
 429       Stats ();
 430
 431       void messages_sent (size_t message_length);
 432       CORBA::LongLong messages_sent () const;
 433       CORBA::LongLong bytes_sent () const;
 434
 435       void messages_received (size_t message_length);
 436       CORBA::LongLong messages_received () const;
 437       CORBA::LongLong bytes_received () const;
 438
 439       void opened_since (const ACE_Time_Value& tv);
 440       const ACE_Time_Value& opened_since () const;
 441
 442     private:
 443       CORBA::LongLong messages_rcvd_; // 32bits not enough (?)
 444       CORBA::LongLong messages_sent_; // 32bits not enough (?)
 445
 446       ACE_Basic_Stats bytes_rcvd_;
 447       ACE_Basic_Stats bytes_sent_;
 448
 449       ACE_Time_Value  opened_since_;
 450     };
 451 ...
 452 </PRE>
 453
 454 <P>
 455 To gather the statistics the TAO_Transport::send_message_shared() and TAO_Transport::process_parsed_messages() must be modified. These are non-virtual methods and are being called as part of request and reply processing regardless of what the most derived Transport type is. This property ensures that any specific Transport will have access to these statistics.
 456 </P>
 457
 458 <H3>
 459 Performance Impact
 460 </H3>
 461
 462 <P>
 463 As the implementation of the Transport Current functionality
 464 necessitates some additional processing on the critical path of an
 465 invocation, we are expecting a performance impact when the
 466 functionality is being used.
 467 </P>
 468
 469 <P>
 470 It is possible at build time, to
 471 disable the functionality, so that applications only incur the penalty
 472 if they require the features. The ORB, by default enables the Transport::Current
 473 functionality. Adding "transport_current=0" to your default.features file will
 474 disable it.
 475 </P>
 476
 477 <H3>
 478 Example Code
 479 </H3>
 480
 481 <P>
 482 Look at $TAO_ROOT/orbsvcs/tests/Transport_Current for code which illustrates and tests this feature.
 483 </P>
 484 </BODY>
 485 </HTML>