| blob | c1a16aa8f28740258d723ad9c00adc8d318b5f1c |
2 <html>
3 <head>
7 <!-- -->
8 </head>
9 <body>
11 <center>
12 <h3>
13 Features Documentation</h3></center>
14 This page is not a tutorial on Real-Time CORBA, but is rather a supplement
15 to the specification, covering all implementation-specific details. Sample
16 code exercising RTCORBA features can be found in
18 We hope to have tutorial-style examples available in the near future.
19 <h3>
21 In order to use features from the Real-Time CORBA 1.0 specification in
22 TAO, a RT-CORBA client application must link with the RTCORBA library;
23 a RT-CORBA server application must link with the RTCORBA library and the
24 RTPortableServer libraries. Since some features in RT-CORBA depend on the
26 set to
29 <p>By default, both Real-Time CORBA and Messaging are enabled in TAO unless
33 <h3>
35 TAO provides three Priority Mappings: Direct, Linear, and Continuous. If
36 no mapping is specified, Direct Priority Mappings will be used. Note that
37 Continuous was previously referred to as Direct.
38 <dl>
39 <dt>
42 <dd>
43 Maps CORBA priorities directly to native priorities.</dd>
45 <dt>
48 <dd>
49 Maps each individual native priority to a contiguous range of CORBA priorities,
50 so that the complete CORBA priority range is used up for the mapping. See
51 <tt>$TAO_ROOT/tao/RTCORBA/Linear_Priority_Mapping.cpp
52 </tt>for
53 more details.</dd>
55 <dt>
58 <dd>
61 is mapped to CORBA priority 0, next higher native priority is mapped to
62 CORBA priority 1, and so on. Since in all the operating systems where TAO
63 is supported the native priority set contains less than 32767 priorities,
64 part of the CORBA priority range is left unused. Consider NT Direct priority
66 to CORBA priorities 0 1 2 3 4 5 6, respectively, and the rest of the CORBA
67 priority range is not used.</dd>
68 </dl>
69 Priority mappings implement the rules for mapping CORBA priority range
71 in some operating systems, the the native OS priority range depends on
72 the scheduling policy being used. That's why when specifying a priority
73 mapping, scheduling policy must be specified as well. Below, we describe
74 how to configure TAO to use a particular priority mapping and scheduling
75 policy. Note, in some operating systems super user privileges are required
76 for use of some of the scheduling policies.
77 <p>By default TAO uses Direct priority mapping and
79 scheduling policy. There are two ways for an application to override these
80 settings:
81 <ol>
82 <li>
84 policy the ORB will use. (This method does not allow the specification
85 of user-defined mappings.) Config file should contain the following options:</li>
92 <i>mapping_type</i> -ORBSchedPolicy
94 <p>where valid values for <i>mapping_type</i> are <tt>continuous</tt>, <tt>linear</tt> and <tt>direct,</tt>
98 <li>
100 priority mapping and scheduling policy with another ORB-defined mapping/scheduling
102 a reference to the priority mapping object used by the ORB. Code excerpts
103 below demonstrate how to perform each of these tasks.</li>
109 <p>Obtaining Priority Mapping Manager:
113 <p>Overriding priority mapping/policy in effect with another ORB-defined
114 mapping/policy combination:
121 <br>or
123 <br>or
129 Priority Mapping Manager takes the ownership of the priority mapping object.
130 <p>Overriding the default with user-defined priority mapping:
136 <p>Obtaining a pointer to the priority mapping object being used by the
137 ORB:
142 <h3>
144 Real-Time CORBA 1.0 does not specify ORB defaults for the policies it defines,
145 leaving it up to implementations. Below is a summary TAO defaults.
148 <tr>
152 </tr>
154 <tr>
158 IIOP) and any explicitly specified by the user (e.g., SHMIOP), in the order
161 </tr>
163 <tr>
167 </tr>
169 <tr>
173 POA creation, the default thread-pool will be used for that POA.</td>
174 </tr>
176 <tr>
180 </tr>
182 <tr>
186 </tr>
188 <tr>
192 </tr>
194 <tr>
199 </tr>
200 </table>
202 <h3>
205 <ul>
206 <li>
207 ThreadPools are now fully supported. Endpoint priorities are no longer
208 supported.</li>
209 <li>
210 By default dynamic RTCorba threads live forever after they are created.
213 can be specified that the dynamic threads should end after a given
214 idle time. Timeout must be specified in microseconds, 0 means the threads
216 specify the amount of time after a dynamic thread ends itself.
217 </ul>
219 <h3>
221 The table below lists all possible configurations of policies involving
222 priorities, and summarizes the semantics of each configuration.
225 <tr>
231 </tr>
233 <tr>
241 </tr>
243 <tr>
249 must be equal to the priority of one of the threadpool lanes. (Same goes
250 for priorities of all the objects registered with the target POA).</td>
253 </tr>
255 <tr>
261 the priority of one of the threadpool lanes.</td>
264 </tr>
266 <tr>
274 </tr>
276 <tr>
282 must be equal to the priority of one of the threadpool lanes. (Same goes
283 for priorities of all the objects registered with the target POA). In addition,
284 each of the priority bands must cover at least one of the threadpool lane
285 priorities.</td>
288 </tr>
290 <tr>
296 of the priority bands. In addition, each of the priority bands must cover
297 at least one of the threadpool lane priorities.</td>
300 which matches the priority band used by the client.</td>
301 </tr>
303 <tr>
311 </tr>
313 <tr>
321 threadpool's default priority. Application level processing is done at
322 the servant's priority.</td>
323 </tr>
325 <tr>
332 threadpool's default priority. Application level processing is done at
333 the client-propagated priority.</td>
334 </tr>
336 <tr>
344 </tr>
346 <tr>
352 must fall into one of the priority bands. (Same goes for priorities of
353 all the objects registered with the target POA).</td>
356 threadpool's default priority. Application level processing is done at
358 is used to restrict the allowed priority values for the servant.</td>
359 </tr>
361 <tr>
367 of the priority bands.</td>
370 threadpool's default priority. Application level processing is done at
372 is used to restrict the allowed priority values for the client.</td>
373 </tr>
374 </table>
376 <h3>
379 if one doesn't already exist, and verifies policy overrides for the <i>invoking
380 thread/ its priority/ target object</i> combination. To establish all connections
383 priority/ object</i> combinations that will be used.
384 <h3>
387 specification, TAO provides configurable properties for each protocol it
388 supports. Below is a summary of all protocol properties available in TAO.
389 <ul>
390 <li>
395 (standard)
398 <tr>
402 </tr>
404 <tr>
408 </tr>
410 <tr>
414 </tr>
416 <tr>
420 </tr>
422 <tr>
426 </tr>
428 <tr>
432 </tr>
433 </table>
435 <li>
440 (TAO-specific)
443 <tr>
447 </tr>
449 <tr>
453 </tr>
455 <tr>
459 </tr>
460 </table>
462 <li>
467 (TAO-specific)
470 <tr>
474 </tr>
476 <tr>
480 </tr>
482 <tr>
486 </tr>
488 <tr>
492 </tr>
493 </table>
494 </ul>
495 Real-Time CORBA 1.0 does not define how protocol properties are created.
508 can be instantiated directly as needed.
509 <p>The table below summarizes how protocol policies overrides affect protocol
510 selection and configuration in TAO.
513 <tr>
521 </tr>
523 <tr>
528 <td>ORB
531 <td>ORB
532 <br>(If no protocol properties are specified at the ORB level, default
533 protocol configurations are used.)</td>
534 </tr>
536 <tr>
541 <td>ORB
542 <br>Current
545 <td>ORB
546 <br>(If no protocol properties are specified at the ORB level, default
547 protocol configurations are used.)</td>
548 </tr>
549 </table>
552 no effect when RTCORBA is enabled.
553 <p>Protocol policies do not depend on any other Real-Time CORBA features
554 and can be used alone. In fact, we plan to make protocol policies available
555 outside RTCORBA, and better integrate them with the Pluggable Protocols
556 framework in the near future.
557 <br>
558 <hr>
559 <h3>
562 <p>Though the RT-CORBA specification details the real-time ORB, thread
563 priorities, and application scheduling requirements, it is less
564 explicit about the communication transport and the underlying
565 network priorities. Our research involved using Differentiated Services
566 technology to prioritize the RT-CORBA traffic in the network. This
567 effort required two essential enhancements to the TAO ORB. First, we
568 provided an efficient and flexible way of setting the DSCP codepoints
569 in the data packets, which is done by extending the ORB protocol
570 properties. DSCP codepoints can dynamically change, based on many
571 factors like QoS feedback received from external QoS monitoring
572 resources or even a change in the application policy. Second, we
573 provide a mechanism to map the RT-CORBA priorities to the Diff-Serv
574 network priorities. The detials of the implementation follows.
575 <dl>
576 <dt>
580 <ul>
581 <li>
585 <dd>
586 The TCP protocol properties interface was extended to add a flag, enable_network_priority.
587 When this flag is set to 1 the RTCORBA priority is mapped to network priority
588 (diffserv codepoint - DSCP) and this priority is set on the GIOP requests
589 and replies. When the flag is not set no network priorities are set on
590 the GIOP requests and replies and are hence best effort.</dd>
591
602 <li>
605 <dd>
606 <p>Support was added for mapping RTCORBA priority to Network Priority. It
607 is similar to the RTCORBA to native thread priority mapping.</dd>
612 <dt>
616 <ul>
617 <li>
620 <br><br>
621 <dd>
623 flag implies the setting/unsetting of the network priority.</dd>
627 <br><tt>
628 recv_buffer_size,</tt>
629 <br><tt>
631 <br><tt>
633 <br><tt>
635 <br><tt>
636 enable_network_priority);</tt>
643 ());</tt>
652 will apply to every invocation made with this ORB.
658 <br><tt>
659 CORBA::SET_OVERRIDE);</tt>
661 set will apply to all the invocations made in the corresponding thread
662 only. All other invocations will have the TCP protocol properties set at
663 the ORB level.
665 <br>
666 CORBA::SET_OVERRIDE);
668 set will apply to the invocations made on the corresponding object only.
670 <br><tt>
671 CORBA::SET_OVERRIDE);</tt>
673 <p>The above steps can be applied repeatedly to create and set TCP protocol
674 properties on the client to enable/disable network priority on the GIOP
675 requests. Since the TCP protocol properties are updated per invocation
676 the most recently set policy will apply.
678 <li>
682 <dd>
684 flag implies the setting/unsetting of the network priority.</dd>
688 <br><tt>
689 recv_buffer_size,</tt>
690 <br><tt>
692 <br><tt>
694 <br><tt>
696 <br><tt>
697 enable_network_priority);</tt>
704 ());</tt>
719 <br><tt>
720 poa_manager.in (),</tt>
721 <br><tt>
722 poa_policy_list );</tt>
723 <p>All the servants that want network priority set on their replies should
724 register with this POA.
725 <p>NOTE - The POA policy can be set only once. This implies that all replies
726 sent from the POA that has the network priority set will have the DSCP
727 set on them. In order to unset the network priority one has to use a different
728 POA without the network priority set on it.
731 <dt>
735 <ul>
736 <li>
740 <dd>
741 The RTCORBA to network priority mapping framework is similar to the RTCORBA
742 to native thread priority mapping framework. As mentioned in section 2.1.2
743 this is implemented by providing the native interface NetworkPriorityMapping.
744 The native interface is implemented in the RTCORBAC.h as:
746 <p><tt>typedef TAO_Network_Priority_Mapping
747 NetworkPriorityMapping;</tt></dd>
754 corba_priority,</tt>
755 <br><tt>
758 network_priority,</tt>
759 <br><tt>
762 <p>The methods to_network (…) and to_corba (…) can be implemented differently
763 for different mapping algorithms that can be defined by the application.
765 <li>
769 <dd>
770 TAO implements the default Linear Mapping from RTCORBA to Diffserv Codepoint
771 mapping. Further mappings may be added to TAO. The application can choose
772 these TAO supported mappings through the Service Configurator (svc.conf)
773 files with the following entry:</dd>
776 -ORBPriorityMapping direct <i>-RTORBNetworkPriorityMapping Linear</i>"
778 <li>
782 <dd>
783 A NetworkPriorityMappingManager is defined in TAO to manage the Network
784 Priority Mapping.</dd>
791 <br><tt> TAO_Network_Priority_Mapping_Manager (RTCORBA::NetworkPriorityMapping
792 * mapping);</tt>
794 * mapping);</tt>
799 <p>The application developer can add his custom network priority mappings
800 as described in section 2.3.3 using the NetworkPriorityMappingManager.
802 <li>
806 <dd>
807 In order to implement a custom network priority mapping the application
808 developer should implement the methods of the TAO_Network_Priority_Mapping
809 class. E.g:</dd>
815 corba_priority,</tt>
816 <br><tt>
819 network_priority,</tt>
820 <br><tt>
823 <p>This custom Network Priority Mapping can then be loaded into the Network
824 Priority Mapping Manager as follows:
826 <br><tt>CORBA::Object_var object = orb->resolve_initial_references ("NetworkPriorityMappingManager");</tt>
827 <br><tt>RTCORBA::NetworkPriorityMappingManager_var mapping_manager = RTCORBA::NetworkPriorityMappingManager::_narrow
828 (object.in ());</tt>
832 <br><tt> TAO_Custom_Network_Priority_Mapping);</tt>
833 <p><tt>#Load the custom network priority mapping object in the network
834 priority</tt>
837 <p>This ensures that the Custom Network Priority Mapping will be used to
838 map the RTCORBA priority to the network priority.
839 </ul>
840 <br>
841 </dl>
843 </body>
844 </html>