diff options
Diffstat (limited to 'TAO/docs')
32 files changed, 0 insertions, 12547 deletions
diff --git a/TAO/docs/DIFFERENCES b/TAO/docs/DIFFERENCES deleted file mode 100644 index 0a8dd343d4d..00000000000 --- a/TAO/docs/DIFFERENCES +++ /dev/null @@ -1,360 +0,0 @@ -@(#)DIFFERENCES 1.1 95/09/13 - -[ NOTE that the CORBA 2.0 specifications have now been published, but are -not yet sufficiently available that this document can usefully just list -any differences between that specification and this software. As a rule, -there are no differences between this software and CORBA 2.0 in areas -where CORBA 2.0 has specified an interface. ] - - -This document summarizes known differences between what is implemented in -this software and currently available OMG specifications. As a rule, these -establish compatibility with revised specifications that are currently being -prepared for publication. However, in some cases the differences resolve -problems that are currently being addressed by ORB taskforces. When those -revised CORBA specifications are published, this document will be updated to -reflect any remaining differences from them. - -The reason for those changes is that different specifications were adopted -at the same time and there were in some cases subtle differences which need -to be resolved. Minor errata have also been fixed. None of these changes -are substantial, with the exception of the TypeCode interpreter API which -was added to the C++ mapping. - -Also, note that the goal of this software is fidelity to the IIOP, so that -issues relating (in particular) to the C++ language mapping or other OMG -specifications were judged to be of less importance at this time. - - -DIFFERENCES from IIOP in UNO Spec (95-3-10) -------------------------------------------- -Some changes to the original specification (94-9-32) for the IIOP protocol -were found to be necessary; most related to the subsequently adopted Interface -Repository (IFR) specification (94-11-7). Others resulted from correction -of minor editorial errors, and experience gained as multiple teams implement -to that specification. - -The bulk of those changes have been incorporated into the 95-3-10 document, -but these few have not. - - -CDR TYPECODE INDIRECTION - -An additional constraint on the use of typecode indirection has been -identified. Specifically, the typecode to which an indirection points -be "self-sufficient", and may not point "outside of itself" for any -further indirections. For example, always indirections occur within -encapsulations, so it's OK for the indirection to point anywhere in -that encapsulation, or at the encoded TCKind enum value immediately -before the encapsulation's length. For typecode encapsulations nested -inside other typecode encapsulations, the indirection may point no -further than the outermost encapsulation. - -Also, when an indirection points to another typecode, the byte order -of that other typecode must be deduced from the encoded value found -there. This is straightforward for encoded TCKind values, all of which -fit into a single byte: if the first byte of the word is zero, then -the encoding is big-endian, else it's little-endian. - -Indirecting to another indirection is not allowed, since the byte order -of the encoded offset can't consistently be deduced. - - -MISCELLANY - -The type GIOP::Version is assumed to be identical to IIOP::Version. -As part of the editorial separation of GIOP from its Internet version -IIOP, this typedef was accidentally omitted. - -This implementation of IIOP supports the OMG-IDL Primitive Data Types as -defined in Appendix A of 94-9-32, but with TCKind numbers following the new -tk_exception and tk_alias codes. (That is, rather than using range 21-25, -these TCKind values are in the range 23-27.) - -These data types are currently the topic of an RFP in process in the OMG, -and are not currently defined as part of a current OMG specification. -Clients and servers using these extended data types are relying on CORBA -extensions that are not yet standardized; and should be prepared to change. - - -CORBA 2.0/CORE Differences --------------------------- -As of this writing, the new CORBA 2.0/CORE document has not yet been made -available. This is a modification of the CORBA 1.2 document, with the -addition of (mandatory) extensions from the UNO (94-9-32) specification: -notably DSI and some new object reference operations. This summarizes -differences between the as-yet-unpublished CORBA 2.0/CORE document and -the original text in the UNO specification. - - -DYNAMIC SKELETON INTERFACE - -Since the new "tk_except" typecodes now include the exception ID (this is -the repository ID describing the exception's type) the "exception" operation -used to report an exception through a ServerRequest no longer includes the -exception ID. - -Since the OperationDef entries for attributes are no longer found in the -interface repositories, the ServerRequest convenience operation to return -this has been removed. Application programs (such as bridges) must compare -the operation name string with the prefixes "_get_" and "_set_" to see if -any given operation applies to an attribute. If an operation is one of the -two for which an OMG-IDL "attribute" declaration is shorthand, then the -application must search the interface repository for that attribute. - -(There are in fact three categories of operations on which an object adapter -and implementation collaborate to handle: user defined operations, user -defined attributes, and operations defined by CORBA such as "is_a" and -"get_implementation". Some object adapters, like the BOA, handle this last -category directly, rather than exposing it to applications.) - -The "non_existent" objref operation accidentally used attribute syntax; this -has been corrected. All operations on CORBA::Object references now use -normal operation syntax in their (pseudo) IDL definitions, and are uniformly -prefixed with underscores as part of their C++ mapping. - - -DIFFERENCES from IDL C++ Mapping (94-9-14) ------------------------------------------- -There are four basic ways in which the IIOP framework does not comply -with the OMG's IDL C++ mapping specification, beyond the use of the CORBA2 -module/namespace rather than the CORBA module/namespace. (CORBA2 is used -so that this software can be linked with existing ORBs, which should be -using the CORBA module/namespace already.) - -These ways are beyond the portability-derived use of the "class" construct -(instead of the C++ namespace construct), and the use of CORBA2::Environment -(rather than C++ exceptions), both of which are accomodated by the mapping: - - (1) This framework does not attempt to be complete. - - Completeness is not required to implement the Internet IOP, - so time was not spent in providing a complete mapping. - - (2) In some cases the API provided is not the one in the mapping. - For example CORBA2::Environment is not always passed in all - operations. This was done to promote ease of implementation - and coding. - - (3) Implementation details are generally exposed. - - This isn't so much a noncompliance issue (it's not specified - that such details must be hidden) as an issue of allowing - noncompliant applications. The effort required to actively - prevent use of implementation details by higher level code - would be nontrivial, and could slow down IIOP code, so no - time was applied to hiding such details. - - (However, note that when the software was modified to use COM, - standard C++ techniques were used to hide most such details.) - - (4) The C++ mapping needs completion in some areas. - - Notably, 94-9-14 does not satisfy requirements to provide - support for for all data types in an "Any" or exception without - needing any precompiled data type support routines. The - TypeCode interpreter addresses this issue. - - Some additional operations were not adopted at the time 94-9-14 - was defined; both 94-9-32 and 94-11-7 added new ORB interfaces - which are not found in the initial C++ mapping document. - -With respect to this fourth issue, descriptions of the API extensions -used is provided later in this file. The additional CORBA operations -are not described since their mapping is straightforward if it isn't given -in those documents. - - -ACCESS TO ALL DATA IN "ANY" AND EXCEPTIONS - -The "void *" value in an "Any", and any "CORBA2::Exception *" value, may -always be passed to the TypeCode interpreter (see next). This allows access -to all data held within an "Any" and an Exception. The "void *" value in an -Any with an exception TypeCode is of type CORBA2::Exception *". Due to -the way CORBA is specified, it is not possible to tell whether an "Any" -holding an exception denotes a user or standard (system-defined) exception -except by exhaustive comparison against exception IDs. - -Also, _all_ legal OMG-IDL data types may be held in an "Any", and may be -manipulated using the TypeCode interpreter. This satisfies a language -mapping requirement that DII (and DSI) be able to manipulate all OMG-IDL -data types without requiring compiler generated support for them. - - -TYPECODE INTERPRETER - -In any given C/C++ execution environment there is a binary standard for how -data is represented. While that standard will differ between execution -environments, there are a very limited number of ways in which those -representations differ. Those differences are encapsulated only in the -TypeCode interpreter, so that portable applications using the dynamic -typing infrastructure in the ORB can completely ignore how it's done in -any particular environment. - -The APIs in this software distribution have been suggested for adoption as -part of the OMG specification suite. The two APIs are nonstatic member -functions in the C++ mapping's TypeCode pseudo-object, and are augmented -by a single new enumeration type. - - unsigned long size() - - This returns the size of an instance of the type that is - described by the TypeCode. - - For example, when invoked on the typecode constant CORBA::_tc_Short, - the value returned is sizeof(CORBA::Short); and when invoked on the - typecode for a structure, it is the size of that structure (including - any internal and tail padding needed). When invoked on a sequence - typecode, it returns a value that does not include the size for - any embedded buffer. - - enum traverse_status {TRAVERSE_STOP, TRAVERSE_CONTINUE }; - - This is a data type used in the traverse() member function. - It allows data type traversal to be terminated early for - non-exceptional conditions, and eliminates the confusion - that some similar APIs have created when they use a single - boolean value (does TRUE mean to stop, or to continue?). - - traverse_status traverse ( - const void *value1; - const void *value2 - traverse_status visit ( - TypeCode_ptr tc, - const void *visit_value1, - const void *visit_value2, - void *visit_context - ), - void *context - ); - - (In the current language mapping, CORBA2::Environment references - are passed as the final parameter to the 'traverse' and 'visit' - routines for use when reporting exceptions.) - - The pointers "value1" and "value2" point to instances of the - data type described by the typecode (or are null pointers). - - For each constituent of that data type (e.g. structure member) - the visit() routine is called once. The constituent's type - is described by "tc"; "visit_value1" points to the constituent - of that type in "value1" (assuming the traverse routine was - not passed a null pointer) and similarly for "visit_value2". - The "visit_context" parameter is the context parameter passed - to the traverse() routine, and can point to whatever data is - needed by the visit() routine. - - Members are traversed in first-to-last order, as defined in the - IDL specification for the data type. So for example, the - visit routine for a structure could print out each element - on a IO stream passed through the context parameter, perhaps in - a neatly formatted form intended for human consumption. - - The visit() function may choose to recursively traverse() each - element. So for example if "tc->kind()" in a visit routine - returned CORBA::tk_struct, the contents of that struct would - be ignored unless the visit routine invoked traverse() using - the typecode and values passed to it. - - If the visit() routine returns TRAVERSE_CONTINUE, succeeding - constituents of the data type are visited in turn; if it - returns TRAVERSE_STOP, the traverse() routine returns that - value to its caller. Of course, if a visit() routine calls - traverse() itself, it may choose to ignore TRAVERSE_STOP. - -The traverse() routine is a powerful tool. It is used in the IIOP code -itself in several ways; look at such use for tutorial details. You could -implement data value comparison and "debug" data dumping as simple exercises -in the use of these APIs. - -The "marshaling interpreter" (marshal.cc) uses it to encode and decode -values according to the IIOP protocol specification. The "Any" code -(any.cc) uses traverse() both to free embedded pointers, and to make "deep" -copies of any data structure given its TypeCode. - -Only that "deep copy" visit routine uses "value2" as anything other than a -null pointer; it allows efficient construction of "deep copies" without -needing extra space for temporary values or coroutine stacks. (A general -purpose two-value comparison could also use "value2".) Most uses of the API -only manipulate a single data value at a time; no realistic need has yet -been seen for manipulating more than two data values at once. - -With respect to the OMG C and C++ mappings, it is clear that this style API -must be provided for the C mapping, but some people have noted that a -"purer" object oriented style API could also be provided in C++. That style -would use another internal visit routine, performing the requisite "switch" -over the fixed number of TCKind values, and then make a virtual function -call to an instance of a C++ class whose private state was the "context" and -whose member functions matched the arms of the switch. - - -MEMORY ALLOCATION - -In order to dynamically manipulate instances of arbitrary data types, -applications need to be able to allocate and free memory. The OMG C++ -mapping only says how to do this for data types which have static C++ -interfaces defined, which is clearly inadequate for using constructed -types with the DII/DSI/Any family of interfaces. - -This infrastructure requires the standard "malloc" and "free" primitives to -be used, and cast to the appropriate type. Data allocated using malloc -will normally be sized according to TypeCode::size(), and then be stored -inside an Any. When the Any is deleted, if the ORB deallocates the memory -it always uses "free" (including for any nested pointers, and correctly -handling cases such as arrays and sequences). - -Note that to support implementations where C and C++ language bindings -share the same ORB infrastructure, this solution is inadequate. This is -because the C binding's CORBA_free() interface would have no way to -determine the type of the data being freed. Instead, typed allocation -APIs will need to be used even when using the dynamically typed CORBA -subsystem ... a TypeCode::malloc() routine would suffice, if it returned -memory that was internally tagged with that TypeCode. In such a case, -the CORBA_free() routine could use that TypeCode to "deep free" data as -required, and C++ "new" and "delete" operators would need to know about -the internal tagging for all those data types. Such tagged allocation -would need to be used for all data that was to be freed by the ORB. - -(Having the C mapping require use of "typed free" routines, instead of the -CORBA_free interface, is sufficient to eliminate this problem.) - - -PASSING EXCEPTIONS THROUGH THE DII - -The C++ mapping's Dynamic Invocation Interface (DII) has key omissions -in that it doesn't say how to access to user-defined exception values, -and implicitly requires ORBs either to pass "excess" data on the wire -or else to consult an interface repository to deal with exceptions or -(deprecated) "context" strings. - -This software changes the DII specification in two ways to support the -requirement for DII users to be able to see user-defined exceptions, yet -not to violate the OMG-IDL type model by reporting illegal exceptions: - - * The Object::_create_request() member function, through which DII - users provide all the information included in an IDL operation's - signature, has an additional parameter. - - That parameter is a sequence of exception typecodes, describing - the user-defined exceptions that the operation can return. (The - standard exceptions defined in CORBA may always be returned.) - When any other exception is returned, the client's ORB reports that - the object's type definition has been violated by the server's ORB. - - * The TypeCode interpreter (see above) may be used to examine all - exception values reported through a CORBA::Environment. A new - Exception::id() operation may be used to determine which typecode - should be used. - -Note that a number of portability and specification problems have been -identified in the current C++ mapping for DII, e.g. for details of memory -management. Later versions of this code may attempt to closely comply -with an improved mapping for DII, to the extent that the interpretation -used here differs from that more unambiguous specification. - -Since there is no efficient way to distinguish typecodes for user defined -exceptions from ones for system-defined ("standard") exceptions (comparing -the exception ID against all the system defined ones is inefficient :-) -a new enum type "ExceptionType" is defined. (An analogous type is already -defined for the C language mapping.) This is used to report exceptions -through DII and DSI. diff --git a/TAO/docs/HISTORY b/TAO/docs/HISTORY deleted file mode 100644 index d97a8e35b2e..00000000000 --- a/TAO/docs/HISTORY +++ /dev/null @@ -1,44 +0,0 @@ -@(#)HISTORY 1.1 95/09/13 - -Mmmmmmmm DD, 1995 -- RELEASE 1.3: ---------------------------------- -Release 1.3 includes bugfixes, and support for the COM binary interface -model, both on UNIX and on MS-Windows platforms. The source tree has -been considerably restructured, with the goal of enabling addition of -other components at both the binary and source levels. - - -September 1, 1995 -- RELEASE 1.2: ---------------------------------- -Release 1.2 includes fixes for problems noted in the recent multivendor -interoperability testing at Object World, and as reported by other users on -the Internet. The most notable of these is that in some cases, when using -multiple connections to IIOP servers and clients, the connection management -code previously would get confused about which connection was which. (One -consequence of fixing this is that an old test has been removed.) Also, -there was no simple way to use Solaris 2.4 threads; see the Makefile for -details. A few other minor features were added to facilitate use of this -code for more than just protocol testing. - - -June 28, 1995 -- RELEASE 1.1: ------------------------------ -Release 1.1 includes support for several new platforms. Particular thanks -go to the team at APM, which contributed the bulk of the new "autoconf" -support (substantially enhancing portability), support for DEC Alpha and -HP 9000 platforms, runtime initialization of the size and alignment table -used to drive the typecode interpreter, and more; see README.apm for details. - -Release 1.1 includes POSIX.1c threading support; on platforms which provide -POSIX.1c threads, applications will be able to take advantage of them. - -Union and indirection support has been added to the TypeCode interpreter, -and more typecode utility APIs have been implemented. Various bugfixes and -cleanup have also been provided. Unfinished stubs for the COS Naming service -are included; these rely on C++ exception support. - - -March 21, 1995 -- RELEASE 1.0: ------------------------------- -The original release ran on a set of UNIX platforms (including Solaris, -SunOS, Linux, and NEXTSTEP) as well as with 16-bit and 32-bit MS-Windows. diff --git a/TAO/docs/INS.html b/TAO/docs/INS.html deleted file mode 100644 index b08247c97ec..00000000000 --- a/TAO/docs/INS.html +++ /dev/null @@ -1,142 +0,0 @@ - <!-- $Id$ --> -<HTML> - -<HEAD> -<TITLE>TAO Interoperable Naming Service</TITLE> - -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<HR><P> -<H3>TAO Interoperable Naming Service</H3> - -The CORBA <A -HREF="ftp://ftp.omg.org/pub/docs/orbos/98-10-11.pdf">Interoperable -Naming Service</A> (INS) service allows the ORB to be configured -administratively to return object references from -<CODE>CORBA::ORB::resolve_initial_references</CODE> for non-locality -constrained objects. The service also introduces the -<CODE>iioploc</CODE> and <CODE>iiopname</CODE> IOR formats, which can -be used to bootstrap services not available at ORB installation time. -<P> - -This document presents an overview of TAO's INS implementation and -addresses common questions. <P> - -<HR align=left width=80% ><P> -<H4>How does <CODE>resolve_initial_references</CODE> work ?</H4><P> - -The following is the order that <CODE>resolve_initial_references</CODE> -locates a service: <P> - -<OL> -<LI><A HREF="#oir">ORBInitRef</A> <br> -<LI><A HREF="#odir">ORBDefaultInitRef</A> <br> -<LI>ORB Default Settings <br> -<LI>Multicast to Service <p> -</OL> - -TAO uses the <A -HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/man/html/ACE_Hash_Map_Manager.html">ACE_Hash_Map_Manager</A> -to keep track of the ObjectID:IOR mappings specified on the -command-line. The IOR could be in <CODE>IOR</CODE>, <CODE>iiop</CODE>, -or <CODE>iioploc</CODE> format. If the ORB fails to resolve the IOR -using the command-line parameters or the default settings, it uses UDP -multicast to resolve the service. <P> - -The Naming Service process acts as an IIOP Agent to respond with the -IOR for the given service name. If the service being resolved is the -Naming Service or the Trading Service, TAO checks the appropriate <A -HREF="Options.html#ev">environment variables</A> prior to using -multicast to obtain the appropriate port number or IOR.<p> - -The following diagram illustrates the order in which these various -components interact. <P> - -<img width=200 height=5 -src="http://www.cs.wustl.edu/~schmidt/gifs/space.gif"><img width=723 -height=529 -src="http://www.cs.wustl.edu/~schmidt/gifs/interop-naming.gif"><p> - -<HR align=left width=80% ><P> - -<H4>ORB Parameters Used for Configuration</H4> -<A NAME="oir"></A> -<DL> -<DT> <img alt="o" src="http://www.cs.wustl.edu/~schmidt/gifs/misc/redball.gif"> -<B><FONT COLOR="#000000">-ORBInitRef :</FONT> </B> -The ORB initial reference argument allows specification of an - arbitrary object reference for an initial service. The format is : - <p> - <CODE>-ORBInitRef [ObjectID]=[ObjectURL]</CODE> <p> - Examples of use are: <p> - <CODE>-ORBInitRef NameService=IOR:0002342344AB345</CODE> ...<br> - <CODE>-ORBInitRef MyServiceID=iioploc://tango.cs.wustl.edu:87777/myService </CODE><p> - - This mechanism allows an ORB to be configured with new initial - service Object IDs that were not defined when the ORB was - installed. The ObjectURL can be any of the URL schemes supported - by <CODE>CORBA::ORB::string_to_object</CODE>.<p> - - <A NAME="odir"></A> -<DT> <img alt="o" src="http://www.cs.wustl.edu/~schmidt/gifs/misc/redball.gif"><B><FONT COLOR="#000000"> --ORBDefaultInitRef :</FONT></B></LI> -The ORB default initial reference argument assists in resolution of - initial references not explicitly specified with - <CODE>-ORBInitRef</CODE>. <CODE>-ORBDefaultInitRef</CODE> requires a URL that, after - appending a slash '/' and a stringified object key, forms a new - URL to identify an initial object reference. <p> - For example: <P> - <CODE>-ORBDefaultInitRef - iioploc://tango.cs.wustl.edu:89899,merengue.cs.wustl.edu:99990</CODE> <p> - - A call to <CODE>resolve_initial_references ("NameService")</CODE> with this - argument results in a new multiple profile URL equivalent to the following: <P> - <CODE>iioploc://tango.cs.wustl.edu:89899/NameService</CODE> <br> - <CODE>iioploc://merengue.cs.wustl.edu:99990/NameService</CODE> <p> - - The URL is passed to <CODE>CORBA::ORB::string_to_object</CODE> to obtain the - initial reference for the service. -</DL> - -<HR align=left width=80% ><P> - -<H4>iioploc:// IOR format</H4> -The <CODE>CORBA::ORB::string_to_object</CODE> now understands the <CODE>iioploc://</CODE> -format IORs. These are user-friendly multiple end-point IORs. For -example - <p> - <img width=50 height=5 -src="http://www.cs.wustl.edu/~schmidt/gifs/space.gif">iioploc:1.0//tango.cs.wustl.edu:99999/SimpleKey, -merengue.cs.wustl.edu:99990/SimpleKey <p> - -Each of the end-points is converted into an IIOP Profile. These -profiles are used to construct the Multiple Profile Object. This -object is then used to construct the Object Reference.<p> - -The object references constructed using this format have a -'SimpleKey' in the Object Key field of the IOR. The server side ORB -intercepts the incoming IIOP request, recognizes the Simple Key and -looks up a table to get the complete IOR. It then raises a -LOCATION_FORWARD or an OBJECT_NOT_EXIST exception to forward/fail the -request depending on if a mapping for the given simple key exists. <p> - -All default TAO Object keys are preceded by a special sequence of -octets ^t^a^o/0. This is taken care of by the POA when it generates -the Object key for the IOR. The sequence is useful for the ORB to -distinguish a simple key from the usual TAO object key. <p> - -<HR align=left width=80% ><P> - -<!--<EM> -Visitor #1 since Thu Apr 15 22:33:36 1999 - -from merengue.cs.wustl.edu - -<EM><br> --> -<I> Last modified Tue Apr 20 14:47:21 CDT 1999 </I> - - -</BODY> -</HTML> diff --git a/TAO/docs/Options.html b/TAO/docs/Options.html deleted file mode 100644 index 365b31ab914..00000000000 --- a/TAO/docs/Options.html +++ /dev/null @@ -1,702 +0,0 @@ -<HTML> -<HEAD> -<!-- $Id$ --> -<META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> -<TITLE>Options for TAO Components</TITLE> -</HEAD> - -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<HR><P> -<H3 ALIGN=CENTER>Options for TAO Components</H3> - -<H3>Overview</H3> -<blockquote> - -<P>Certain components in TAO such as the ORB Core or Object Adapter -can be tuned by users by providing value for options or environment -variables to them. These options are commonly specified as (1) -environment variables or (2) strings passed on the command-line. They -are generally passed to component initialization methods for -consumption.</P> - -<p>Both command-line options and environment variables are used to -control the global ORB features like the IOR format or ORB's -bootstraping methods. Options in <code>svc.conf</code> file on the -other hand provides a mechanism to fine-tune the internal components -in TAO and they are specific to individual components. -<code>svc.conf</code> files are not required to run TAO programs. -However, if you know the behavior of your programs, you can tune-up -your programs and use various optimization provided by TAO thru the -use of svc.conf files.</p> - -<P><EM>Programmer's Note:</EM> the internal structure for options is -the traditional <CODE>argc</CODE>/<CODE>argv</CODE> vector of strings -style popularized by C and Unix. By convention, an initialization -method will consume, <EM>i.e.</EM>, remove from the vector, any -options that it recognizes.</P> </blockquote> - -<HR><P> -<H3><A NAME="ev">Environment Variables</A></H3> - -The following environment variables are supported by TAO: - -<BLOCKQUOTE> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Environment Variable</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE>NameServiceIOR</CODE> <EM>which</EM></TD> - <TD> - Specifies which IOR the Naming Service is listening on. - </TD> - </TR> - <TR> - <TD><CODE>NameServicePort</CODE> <EM>which</EM></TD> - <TD> - Specifies which port the Naming Service is listening on for multicast - requests. - </TD> - </TR> - <TR> - <TD><CODE>TradingServiceIOR</CODE> <EM>which</EM></TD> - <TD> - Specifies which IOR the Trading Service is listening on. - </TD> - </TR> - <TR> - <TD><CODE>TradingServicePort</CODE> <EM>which</EM></TD> - <TD> - Specifies which port the Trading Service is listening on for multicast - requests. - </TD> - </TR> -</TABLE> -</P> -</BLOCKQUOTE> - -<HR><P> - -<H3>Types of Options</H3> - -<blockquote> -<P>The following components can be tuned via options:</P> - -<UL> - <LI><A HREF="#ORB"><CODE>CORBA::ORB</CODE></A> - <LI><A HREF="#ResourceFactory"><CODE>TAO_Resource_Factory</CODE></A> - <LI><A HREF="#DefaultServer"><CODE>TAO_Default_Server_Strategy_Factory</CODE></A> - <LI><A HREF="#DefaultClient" TARGET="_top"><CODE>TAO_Default_Client_Strategy_Factory</CODE></A> -</UL> - -Typically, CORBA::ORB options are set via command line parameters, -while the rest of the options are set via the service configurator -(svc.conf) file. - -</blockquote> - -<blockquote> -<H3><CODE>CORBA::ORB</CODE><A NAME="ORB"></A></H3> - -<p><em>Note:</em> <code>-ORBGlobalCollocation</code> flag has been -merged with <a href="#-ORBCollocation"><code>-ORBCollocation</code></a>. - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING= "0"> - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <!-- <TR NAME="ORBsvcconf"> --> - <tr> - <TD><CODE>-ORBSvcConf</CODE> <EM>config file name</EM></TD> - <TD>Specifies the name of the file from which it will read dynamic service configuration - directives <EM>ala</EM> ACE's Service Configurator. By - default, a service configurator-based application will look - for a file named "svc.conf" in the current directory.</TD> - </TR> - <tr> - <TD><CODE>-ORBSvcConfDirective</CODE> <EM>directivestring</EM></TD> - <TD>Specifies a service configuration - directive, which is passed to ACE's Service Configurator.</TD> - </TR> - <TR> - <TD><CODE>-ORBDaemon</CODE></TD> - <TD>Specifies that the ORB should <I>daemonize</I> itself.</TD> - </TR> - <TR> - <TD><CODE>-ORBDebug</CODE></TD> - <TD>Turns on the output of debugging messages within ACE's Service Configurator - componentry.</TD> - </TR> - <TR> - <TD><CODE>-ORBDebugLevel</CODE> <EM>level</EM></TD> - <TD>Control the level of debugging in the ORB. Higher number produce - more output (try 10). - </TD> - </TR> - <TR> - <TD><CODE>-ORBEndpoint</CODE> <EM>endpoint</EM></TD> - <TD><a name="-ORBEndpoint"></a>Tells the ORB to listen for requests on the - interface specified by <I><EM>endpoint</EM></I>. Endpoints are - specified using a URL style format. An endpoint has the form: - <blockquote><CODE> - protocol://V.v@addr1,...,W.w@addrN - </CODE></blockquote> - where <CODE>V.v</CODE> and <CODE>W.w</CODE> are optional protcol versions for - each address. An example of an IIOP endpoint is: - <blockquote><CODE> - iiop://<I><EM>hostname</EM></I>:<I><EM>port</EM></I> - </CODE></blockquote> - Sets of endpoints may be specified using multiple <CODE>-ORBEndpoint</CODE> - options or by delimiting endpoints with a semi-colon (;). For example, - <blockquote><CODE> - -ORBEndpoint iiop://localhost:9999 -ORBEndpoint uiop:///tmp/mylocalsock - </CODE></blockquote> - is equivalent to: - <blockquote><CODE> - -ORBEndpoint 'iiop://localhost:9999;uiop:///tmp/mylocalsock' - </CODE></blockquote> - Notice the single quotes (') in the latter option specification. Single - quotes are needed to prevent the shell from interpreting text after the - semi-colon as another command to run.<P> - If an endpoint is specified without an <CODE>addr</CODE> such as the following: - <blockquote><CODE> - -ORBEndpoint uiop:// - </CODE></blockquote> - then a default endpoint will be created for the specified protocol. - </TD> - </TR> - - <TR> - - <TD><CODE>-ORBHost</CODE> <EM>hostname</EM></TD> - <TD><a name="-ORBHost"></a>Tells the ORB to listen for requests on the - interface associated with the host named - <I><EM>hostname</EM></I>. This option is valid only for IIOP endpoints.<BR> - <STRONG>NOTE:</STRONG> This option has been superceded by the - <CODE>-ORBEndpoint</CODE> option. It will not be supported in the - future.</TD> - </TR> - - <TR> - - <TD><CODE>-ORBPort</CODE> <EM>portspec</EM></TD> - <TD>Tells the ORB to - listen for requests on the port specified by - <I><EM>portspec</EM></I>. If not specified, the OS gets to choose a - random empty port. This option is valid only for IIOP endpoints.<BR> - <STRONG>NOTE:</STRONG> This option has been superceded by the - <CODE>-ORBEndpoint</CODE> option. It will not be supported in the - future.</TD> - - </TR> - - <TR> - <TD><CODE>-ORBObjRefStyle</CODE> <EM>which</EM></TD> - <TD>Specifies the user-visible style of object references. The range of values - is <CODE>IOR</CODE> (default), which is the traditional nonsensical object reference, - or <CODE>URL</CODE>, which looks more like a URL.</TD> - </TR> - <TR> - <TD><CODE>-ORBRcvSock</CODE> <EM>receive buffer size</EM></TD> - <TD><A NAME="-ORBRcvSock"></a>Specify the size of the socket receive buffer as a positive, non-zero integer. - If not specified, the ACE_DEFAULT_MAX_SOCKET_BUFSIZ default is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBSndSock</CODE> <EM>send buffer size</EM></TD> - <TD><A NAME="-ORBSndSock"></a>Specify the size of the socket send buffer as a positive, non-zero integer. - If not specified, the ACE_DEFAULT_MAX_SOCKET_BUFSIZ default is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBNameServicePort</CODE> <EM>portspec</EM></TD> - <TD>Specifies which port the Naming Service is listening on for - multicast requests. By default, - TAO_DEFAULT_NAME_SERVICE_REQUEST_PORT, which is 10013 is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBNameServiceIOR</CODE> <EM>ior</EM></TD> - <TD>Specifies the IOR for the Naming Service.</TD> - </TR> - <TR> - <TD><CODE>-ORBTradingServiceIOR</CODE> <EM>ior</EM></TD> - <TD>Specifies the IOR for the Trading Service.</TD> - </TR> - <TR> - <TD><CODE>-ORBTradingServicePort</CODE> <EM>portspec</EM></TD> - <TD>Specifies to which port the Trading Service is listening on for - multicast requests. By default, - TAO_DEFAULT_TRADING_SERVICE_REQUEST_PORT which is 10016 is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBImplRepoIOR</CODE> <EM>ior</EM></TD> - <TD>Specifies the IOR for the Implementation Repository.</TD> - </TR> - <TR> - <TD><CODE>-ORBImplRepoPort</CODE> <EM>portspec</EM></TD> - <TD>Specifies to which port the Implementation Repository is listening on for - multicast requests. By default, - TAO_DEFAULT_IMPLREPO_SERVER_REQUEST_PORT which is 10018 is to - be used.</TD> - </TR> - <TR> - <TD><CODE>-ORBCollocation</CODE> <EM>yes/global/per-orb/no</EM></TD> - <TD><a name="-ORBCollocation"></a>Specifies the use of collocation - object optimization. If <em>global</em> or <em>yes</em> is - specified, objects in the same process will be treated as collocated. - If <em>per-orb</em> is specified, only objects in the same ORB are - treated as collocated. When <em>no</em> is specified, no objects are - treated as collocated. Default is global.</TD> - </TR> - <TR> - <TD> - <CODE>-ORBCollocationStrategy</CODE> <EM>thru_poa/direct</EM> - </TD> - <TD> - Specifies what kind of collocated object to use. If the - <em>thru_poa</em> strategy is used, TAO uses the collocation - object implementation that respects POA's current state and - policies. When using the <em>direct</em> strategy, method - invocations on collocated objects become direct calls to servant - without checking POA's status. Default is thru_poa. - </TD> - </TR> - <TR> - <TD><CODE>-ORBPreconnect</CODE> <EM>endpoint</EM></TD> - <TD><A name="-ORBPreconnect"></a>Pre-establishes a blocking connection to - each listed <EM>endpoint</EM>. If a connection cannot be established the - failed preconnection will be ignored and the next preconnection in the list - will be processed. Successful and unsuccessful preconnections will be - displayed if a debugging level greater than or equal to one is specified by - using the <CODE>-ORBDebugLevel</CODE> option. Listing the same combination - multiple times will properly establish multiple connections to that endpoint. - The <CODE>-ORBPreconnect</CODE> option uses the same endpoint format as the - <CODE>-ORBEndpoint</CODE> option. Specifying IIOP endpoints using a comma - delimited list of <EM>host<STRONG>:</STRONG>port</EM> pairs is deprecated - and will not be supported in the future.</TD> - </TR> - <TR> - <TD><CODE>-ORBCDRTradeoff</CODE> <EM>maxsize</EM></TD> - <TD><A name="-ORBCDRTradeoff"></a>Control the strategy to tradeoff - between copy vs no copy marshalling of octet sequences. - If an octet sequence is smaller than <EM>maxsize</EM> and the current - message block contains enough space for it the octet sequence is - copied instead of appended to the CDR stream. By default, - ACE_DEFAULT_CDR_MEMORY_TRADEOFF is used. - </TD> - </TR> - <TR> - <TD><CODE>-ORBSkipServiceConfigOpen</CODE></TD> - <TD><A name="-ORBSkipServiceConfigOpen"></a>Do not call the <code>ACE_Service_Config::open</code> - method, which is necessary if the ORB is being linked dynamically via the ACE Service Configurator - which is not reentrant. Default is </TD> - </TR> - <TR> - <TD><CODE>-ORBGIOPlite</CODE></TD> - <TD><A name="-ORBGIOPlite"></a>Enable a lightweight version of the - GIOP protocol. This protocol removes some of the fields in - the GIOP and the Request header. It only works on - homogenous environments..</TD> - </TR> - <TR> - <TD><CODE>-ORBDottedDecimalAddresses</CODE> <EM>boolean (0 / 1)</EM></TD> - <TD><A name="-ORBDottedDecimalAddresses"></a> Use the dotted decimal - notation for addresses. By default domain names are used in IORs.</TD> - </TR> - <TR> - <TD><CODE>-ORBInitRef</CODE> <EM>ObjectId=IOR</EM></TD> - <TD><A name="-ORBInitRef"></a> Allows specification of an arbitrary - object reference for an initial service. The IOR could be in any - one of the following formats : OMG IOR, URL, iioploc or - file. iioploc is a multiple end-point IOR understood by the - string_to_object () and used as a boot-strapping mechanism by the - resolve_initial_references (). The mappings specified through this - argument override the orb-install-time defaults. The - file://<I>pathname</I> interprets the contents of the <I>pathname</I> file - as an object reference in any of the above formats. </TD> - </TR> - - <TR> - <TD><CODE>-ORBDefaultInitRef</CODE> <EM>IOR prefix</EM></TD> - <TD><A name="-ORBDefaultInitRef"></a> This argument allows resolution of initial references not explicitly specified with -ORBInitRef. It requires a URL prefix that, after appending a slash '/' and a simple object key, forms a new URL to identify an initial object reference. The URL prefix format currently supported is iioploc.</TD> - </TR> - - <TR> - <TD><CODE>-ORBStdProfileComponents</CODE> <EM>boolean (0 / 1)</EM></TD> - <TD><A name="-ORBStdProfileComponents"></a> If <EM>0</EM> then the ORB - does not generate the OMG standarized profile - components, such as the ORB type and codesets. - Notice that the presence of this components is optional - in GIOP 1.1 - The default value is controlled by a compile-time flag - (check orbconf.h).</TD> - </TR> - - <TR> - <TD><CODE>-ORBResources</CODE> <EM>which</EM></TD> - <TD><A name=-ORBResources>Control the use of thread specific resources - in the ORB. - If (<em>which</em> = <code>global</code>) then the - same set of resources are shared by all the threads - that use that ORB. - If (<em>which</em> = <code>tss</code>) then each that - uses that ORB gets its own set of resources. - Currently the resources are limited to the reactor. - </TD> - </TR> - -</TABLE> -</P> -</blockquote> - -<H3><CODE>TAO_Resource_Factory</CODE><A NAME="ResourceFactory"></A></H3> - -<p><em>Note:</em> <code>-ORBReactorLock</code> flag has been superceded by <code>-ORBReactorType</code>. - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE>-ORBResources</CODE> <EM>which</EM></TD> - <TD>Specify whether each thread uses a global - (<em>which</em> = <code>global</code>) or a thread-specific - (<em>which</em> = <code>tss</code>) instance for the resources it - returns. The default is <CODE>global </CODE>. - <B>NOTE:</B> This option controls the default value for - the ORB option of the same name.</A>. - </TD> - </TR> - <TR> - <TD><CODE>-ORBReactorType</CODE> <EM>which</EM></TD> - <TD><a name="-ORBReactorType"></a>Specify what kind of reactor does the - ORB use, the options are: - <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0"> - <TR><TH><em>which</em></TH><TH>Reactor</TH> - </TR> - <TR><TD><CODE>select_mt<CODE></TD><TD>Use the - <CODE>ACE_Select_Reactor</CODE> with the usual - locking mechanism for this platform</TD> - </TR> - <TR><TD><CODE>select_st<CODE></TD><TD>Use the - <CODE>ACE_Select_Reactor</CODE> with null locks - </TD> - </TR> - <TR><TD><CODE>fl<CODE></TD><TD>Use the - <CODE>ACE_FlReactor</CODE> only available if ACE - was compiled with support for the FL toolkit - </TD> - </TR> -</TR> -<TR><TD><CODE>wfmo<CODE></TD> -<TD>Use the - <CODE>ACE_WFMO_Reactor</CODE> only available on - Win32 platforms. -</TD> -</TR> -<TR><TD><CODE>msg_wfmo<CODE></TD><TD>Use the - <CODE>ACE_Msg_WFMO_Reactor</CODE> only available on - Win32 platforms. -</TD> -</TR> -<TR><TD><CODE>tp<CODE></TD><TD>Use the - <CODE>ACE_TP_Reactor</CODE>, a select based - thread-pool reactor. -</TD> -</TR> -</TABLE> -The default is <code>select_mt</code></TD> -</TR> -<TR> - <TD><CODE>-ORBProtocolFactory</CODE> <EM>factory</EM></TD> - <TD><a name="-ORBProtocolFactory"></a> - Specify which pluggable protocol factory to load. By default, - the factories for the IIOP and UIOP protocols (<code>IIOP_Factory</code> - and <code>UIOP_Factory</code>, respectively) are loaded. - <p> - For example, if some protocol called <em><code>Foo</code></em> whose - factory was called <em><code>Foo_Factory</code></em> was available, - then it could be loaded into TAO by specifying - <code>-ORBProtocolFactory Foo_Factory</code> in the service - configurator file. The - <em><code>Foo</code></em> pluggable protocol would then be available - for use. - </TD> -</TR> -<TR> - <TD><CODE>-ORBInputCDRAllocator</CODE> <EM>which</EM></TD> - <TD><a name="-ORBInputCDRAllocator"></a> - Specify whether the ORB uses locked - (<em>which</em> = <code>thread</code>) - or lock-free (<em>which</em> = <code>null</code>) - allocators for the incoming CDR buffers. - Though <CODE>null</CODE> should give the - optimal performance; - we made the default <CODE>thread</CODE>. - TAO optimizations for octet sequences will not work in all cases when - if the allocator does not have locks (for example if the - octet sequences are part of a return value. - Using locked allocators also allows the users to - take advantage of the TAO octet sequence - extensions to preserve the buffer after the upcall. - </TD> -</TR> -</TABLE> -</P> -</blockquote> - -<H3><CODE>TAO_Default_Server_Strategy_Factory</CODE><A NAME="DefaultServer"></A></H3> - -<p><em>Note:</em> <code>-ORBDemuxStrategy</code> flag has been changed to <code>-ORBSystemidPolicyDemuxStrategy</code> and <code>-ORBUseridPolicyDemuxStrategy</code>. -<p><em>Note:</em> <code>-ORBTableSize</code> flag has been changed to <code>-ORBActiveObjectMapSize</code>. - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> - - <TD><a name="orb_concurrency"><CODE>-ORBConcurrency</CODE></a> - <EM>which</EM></TD> - <TD>Specify which - concurrency strategy to use. Range of values is <code>reactive</code> - for a purely Reactor-driven concurrency strategy or - <code>thread-per-connection</code> for creating a new thread to - service each connection. The default is reactive.</TD> - </TR> - <TR> - <TD><CODE>-ORBActiveObjectMapSize</CODE> <EM>active object map - size</EM></TD> - <TD>Specify the size of the active object map. If not - specified, the default value is 64.</TD> - </TR> - <TR> - - <TD><CODE>-ORBUseridPolicyDemuxStrategy</CODE> <EM>user id policy - based demultiplexing strategy</EM></TD> - <TD>Specify the demultiplexing - lookup strategy to be used with the user id policy. The - <EM>demultiplexing strategy</EM> can be one of <CODE>dynamic</CODE> or - <CODE>linear</CODE>. This option defaults to use the - <CODE>dynamic</CODE> strategy. </TD> - </TR> - <TR> - - <TD><CODE>-ORBSystemidPolicyDemuxStrategy</CODE> <EM>system id policy - based demultiplexing strategy</EM></TD> - <TD>Specify the demultiplexing - lookup strategy to be used with the system id policy. The - <EM>demultiplexing strategy</EM> can be one of <CODE>dynamic</CODE>, - <CODE>linear</CODE>, or <CODE>active</CODE>. This option defaults to - use the <CODE>active</CODE> strategy. </TD> - </TR> - <TR> - - <TD><CODE>-ORBUniqueidPolicyReverseDemuxStrategy</CODE> <EM>unique id - policy based reverse demultiplexing strategy</EM></TD> - <TD>Specify the - reverse demultiplexing lookup strategy to be used with the unique id - policy. The <EM>reverse demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to - use the <CODE>dynamic</CODE> strategy. </TD> - </TR> - <TR> - - <TD><CODE>-ORBAllowReactivationOfSystemids</CODE> <EM>allows - reactivation of system ids</EM></TD> - <TD>Specify whether system ids - can be reactivated, i.e., once an id that was generated by the system - has be deactivated, will the user reactivate a new servant using the - old id. If the user is not going to use this feature, the IORs can be - shortened, an extra comparison in the critical upcall path removed, - and some memory on the server side can be saved. The - <CODE>ORBallowreactivationofsystemids</CODE> can be <CODE>0</CODE> or - <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> - <TR> - - <TD><CODE>-ORBActiveHintInIds</CODE> <EM>adds an active hint in - ids</EM></TD> - <TD>Specify whether an active hint should be added to - ids. With active hints, ids can be found quickly. However, they lead - to larger IORs. Note that this option is disregarded - <CODE>-ORBAllowReactivationOfSystemids</CODE> is set to - <CODE>0</CODE>. The <EM>-ORBActiveHintInIds</EM> can be <CODE>0</CODE> - or <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> - <TR> - - <TD><CODE>-ORBPoaMapSize</CODE> <EM>poa map size</EM></TD> - <TD>Specify - the size of the poa map. If not specified, the default value is - 24.</TD> - </TR> - <TR> - - <TD><CODE>-ORBPersiententidPolicyDemuxStrategy</CODE> <EM>persistent - id policy based demultiplexing strategy</EM></TD> - <TD>Specify the - demultiplexing lookup strategy to be used with the persistent id - policy. The <EM>demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to - use the <CODE>dynamic</CODE> strategy. </TD> - </TR> - <TR> - - <TD><CODE>-ORBTransientidPolicyDemuxStrategy</CODE> <EM>transient id - policy based demultiplexing strategy</EM></TD> - <TD>Specify the - demultiplexing lookup strategy to be used with the transient id - policy. The <EM>demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE>, <CODE>linear</CODE>, or - <CODE>active</CODE>. This option defaults to use the - <CODE>active</CODE> strategy. </TD> - </TR> - <TR> - - <TD><CODE>-ORBActiveHintInPOANames</CODE> <EM>adds an active hint in - poa names</EM></TD> - <TD>Specify whether an active hint should be added - to poa names. With active hints, poa names can be found quickly. - However, they lead to larger IORs. The - <EM>-ORBActiveHintInPOANames</EM> can be <CODE>0</CODE> or - <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> - <TR> - - <TD><CODE>-ORBThreadFlags</CODE> <EM>thread flags</EM></TD> - <TD>Specify the flags used for thread creation. Flags can be any - logical-OR combination of <CODE>THR_DETACHED</CODE>, - <CODE>THR_BOUND</CODE>, <CODE>THR_NEW_LWP</CODE>, - <CODE>THE_SUSPENDED</CODE>. The default is <CODE>THR_BOUND </CODE>. </TD> - </TR> - <TR> - - <TD><CODE>-ORBPOALock</CODE> <EM>lock type</EM></TD> - <TD><a - name="-ORBPOALock"></a>Specify the type of lock to be used for POA - accesses. Possible values for <em>lock type</em> are - <code>thread</code>, which specifies that an inter-thread mutex is - used to guarantee exclusive acccess, and <code>null</code>, which - specifies that no locking be performed. The default is - <code>thread</code>.</TD> - </TR> -<!-- - <TR> - - <TD><CODE>-ORBEventLoopLock</CODE> <EM>lock type</EM></TD> - <TD><font color=red>Somebody document me.</font></TD> - </TR> - <TR> ---> - <TD><CODE>-ORBConnectorLock</CODE> <EM>lock type</EM></TD> - <TD><a - name="-ORBConnectorLock"></a>This option has been moved to the - client strategy factory.</TD> - </TR> - -</TABLE> -</P> -</blockquote> - -<H3><CODE>TAO_Default_Client_Strategy_Factory</CODE><A NAME="DefaultClient"></A></H3> - -<BLOCKQUOTE> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE><a name="#-ORBProfileLock">-ORBProfileLock</a></CODE> <EM>which</EM></TD> - <TD> - Specify the kind of synchronization primitive for the - Profiles. - Default is <code>thread</code>, which means that a regular thread - mutex is used. The - second option is <code>null</code>, which means a null lock is used. - This makes sense in case of optimizations and is allowed when - no forwarding is used or only a single threaded client. - </TD> - </TR> - <TR> - <TD><CODE>-ORBClientConnectionHandler</CODE> <EM>MT / ST / RW</EM></TD> - - <TD><A name="-ORBClientConnectionHandler"></a> - - ST means use the single-threaded client connection handler, i.e., the - leader follower model will not be used. However, ST does support - nested upcalls and handling of new requests while waiting for the - reply from a server. <p> - - MT means use the multi-threaded client connection handler which uses - the leader follower model. This model allows the use of multiple - threads with a single Reactor. <p> - - RW selects a strategy that simply blocks in recv() when waiting for a - response from the server instead of waiting in the Reactor. The RW - strategy only works when the application does not have to worry about - new request showing up when waiting for a response. Therefore, this - strategy is appropriate only for "pure" clients. Note that - applications with nested upcalls are not "pure" clients. Also note - that this strategy will only effect two way calls, since there is no - waiting for one way calls. This strategy can also be used in an - application that is both a client and a server if the server side is - handled by a separate thread and the client threads are "pure" - clients. <p> - - Default for this option is MT. - - </TD> - </TR> - - <TR> - <TD><CODE>-ORBTransportMuxStrategy</CODE> <EM>EXCLUSIVE / MUXED</EM></TD> - - <TD><A name="-ORBTransportMuxStrategy"></a> - - EXCLUSIVE means that the Transport does not multiplex requests on a - connection. At a time, there can be only one request pending on a - connection. <p> - - MUXED means that Transport multiplexes more than one request at the - same time on a connection. This is very important for getting the - Asynchronous Method Invocation model to work. This is not - implemented yet. <p> - - Default for this option is EXCLUSIVE. - - </TD> - </TR> - - <TR> - <TD><CODE>-ORBConnectorLock</CODE> <EM>lock type</EM></TD> - <TD><a - name="-ORBConnectorLock"></a>Specify the type of lock to be used by - the connector. Possible values for <em>lock type</em> are - <code>thread</code>, which specifies that an inter-thread mutex is - used to guarantee exclusive acccess, and <code>null</code>, which - specifies that no locking be performed. The default is - <code>thread</code>. - </TD> - </TR> - -</TABLE> -</P> -</BLOCKQUOTE> -</blockquote> - -<P><HR><P> -Back to the TAO <A HREF="components.html">components documentation</A>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> -</HTML> diff --git a/TAO/docs/REFERENCES b/TAO/docs/REFERENCES deleted file mode 100644 index a44ef31c16e..00000000000 --- a/TAO/docs/REFERENCES +++ /dev/null @@ -1,91 +0,0 @@ -@(#)REFERENCES 1.2 95/11/08 - -REFERENCES -========== -Most of the relevant references here are to OMG documents, however there -are a few external references of some note: - - * http://www.uci.agh.edu.pl/research/cs/TOCOOS/COPERNICUS.html - - -OMG REFERENCES --------------- -As of this writing, OMG is in the process of publishing new versions of the -base CORBA specifications, merging specifications as needed into single -documents and splitting out the C mapping from the CORBA/CORE specification. - -This software has made every effort to track both the base documents and the -agreed corrections and revisions. Since those documents have not yet been -published, there will inevitably be areas in which it does not reflect the -versions yet to be published. See the "DIFFERENCES" file for information -about where this software differs from these current base documents: - -* CORBA 2.0/Interoperability: Universal Networked Objects (UNO), OMG - TC Document 95-3-10. This includes the mandatory IIOP and bridging - support, as well as the optional DCE-CIOP protocol. - -* CORBA 1.2 specification, OMG TC Document 93-12-43. This is the - base document on which the CORBA 2.0 CORE specifications build. - -* Universal Networked Objects (UNO), OMG TC Document 94-9-32. Until - the CORBA 2.0/CORE document is published, replacing the CORBA 1.2, - initialisation, and IFR specifications, you must use this earlier - version of UNO to see (only!) the specification for DSI and several - other CORBA CORE extensions (for bridging) adopted by the OMG. - [ NOTE: use the IIOP specification in 95-3-10, not the one here; - 95-3-10 has changes required by the IFR specification, 95-11-7. ] - -* Initialisation, OMG TC Document 94-10-24. This defines the portable - APIs for initialising ORBs. - -* Interface Repository, OMG TC Document 94-11-7. This updates the - CORBA specifications above and is referenced by the UNO document. - -* IDL C++ Language Mapping Specification, OMG TC Document 94-9-14. - This defines the mapping of CORBA 1.2, including OMG-IDL, onto C++. - -There are a few inconsistencies between these documents, which are in the -process of being resolved. The inconsistencies arose because different -groups worked on different parts of the system, at different times and -with some different goals. Contact the various revision committees to -find out how these differences are being resolved: - - - interop@omg.org ... the interop revision task force (RTF) - - cxx_revision@omg.org ... the C++ RTF - - orb_revision@omg.org ... the general ORB RTF - -Also, note that these ORB specifications correspond to only the lowest levels -of OMG's Object Management Architecture. In particular, the "Object Services" -define object interfaces for naming, events, persistence, relationships, -lifecycle, externalization, transactions, and concurrency control. Also, -"Common Facilities" objects will address such things as compound document -architecture. If you intend to develop software based on ORBs, these -specifications are likely to be of interest. The OMA is available in -technical bookstores: - - Richard Soley (ed.), Object Management Architecture Guide, - Second Edition, John Wiley & Sons, New York, 1992. - - -ACQUIRING REFERENCE DOCUMENTS ------------------------------ -To acquire those reference documents, use the OMG document server through -Internet email. Send a message to "server@omg.org", with content lines -such as - - send help - -to get directions about how to use the server, or - - send docs/95-3-10.ps - -to get a PostScript copy of any particular document. (OMG specifications -are available only in PostScript.) - -The OMG document server is maintained for use by OMG members, but is also -available for general Internet access. Only members will be supported in -the case of problems. - -To find out more about the OMG, send email to "omg@omg.org", or look -at the Web page at "http://www.omg.org". - diff --git a/TAO/docs/Tags.html b/TAO/docs/Tags.html deleted file mode 100644 index 4ff3f3160f1..00000000000 --- a/TAO/docs/Tags.html +++ /dev/null @@ -1,231 +0,0 @@ -<HTML> -<HEAD> - <!-- $Id$ --> - <TITLE>Tags used in TAO</TITLE> -</HEAD> - -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - - <HR><P><H3 ALIGN=CENTER>Tags used in TAO</H3></P> - - <H3>Overview</H3> - - <P>The <A HREF="http://www.omg.org/library/c2indx.html">CORBA</A> - specification defines several tags, a.k.a. <EM>magic numbers</EM>, - to distinguish between several otherwise opaque entities. - For example, - all profiles are transmitted as a CDR encapsulation (a sequence - of octets), - using a tag the type of the profile can be determined and the - encapsulation can be properly interpreted. - </P> - <P>To ensure that the tags uniquely indentify the entities in each - namespace the <A HREF="http://www.omg.org/">OMG</A> acts as an - <EM>allocation authority</EM>, - keeps a registry of the tags allocated so far and assigning the - new tag values on demand. - The process to request a tag is very simple, - interested readers can consult - <A HREF="http://www.omg.org/cgi-bin/doc?ptc/99-02-01">this - link</A> - for more details - </P> - - <P>We have reserved several tags for TAO, this page documents - those tags and how they are used, some details are subject to - change. We recommend that interested readers check the - <A HREF="../releasenotes/index.html">release notes</A> - </P> - - <H3>List of TAGS</H3> - - <H4>ORB Type ID</H4> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Hex Value</TH><TH>ASCII Representation</TH> - <TH>Description</TH></TR> - <TR> - <TD>0x54414f00</TD><TD>"TAO\0x00"</TD><TD>IIOP profiles - contain a component list. One of the elements of this - list (the <CODE>IOP::TAG_ORB_TYPE</CODE>) contains a - identifier for the ORB that created the profile. - </TD> - </TR> - </TABLE></P> - - <H4>IOR Profile IDs</H4> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Hex Value</TH><TH>ASCII Representation</TH> - <TH>Description</TH></TR> - <TR> - <TD>0x54414f00</TD><TD>"TAO\0x00"</TD><TD>A TAO local IPC (aka - Unix domain) profile. - </TD> - </TR> - </TABLE></P> - - <P>The range <CODE>0x54414f01-0x54414f0f</CODE> - (<CODE>"TAO\0x01"-"TAO\0x0f"</CODE>) is reserved for future use. - Only for informational purposes we include the following list - of potential uses: - </P> - - <P><TABLE> - <TR><TH>Hex Value</TH><TH>ASCII Representation</TH> - <TH>Description</TH></TR> - <TR> - <TD>0x54414f01</TD><TD>"TAO\0x01"</TD> - <TD>GIOP over ATM/AAL5</TD> - </TR> - <TR> - <TD>0x54414f02</TD><TD>"TAO\0x02"</TD> - <TD>Shared memory transport</TD> - </TR> - <TR> - <TD>0x54414f03</TD><TD>"TAO\0x03"</TD> - <TD>Message queue</TD> - </TR> - <TR> - <TD>0x54414f04</TD><TD>"TAO\0x04"</TD> - <TD>UDP</TD> - </TR> - <TR> - <TD>0x54414f05</TD><TD>"TAO\0x05"</TD> - <TD>IP multicast</TD> - </TR> - <TR> - <TD>0x54414f06</TD><TD>"TAO\0x06"</TD> - <TD>Compact PCI bus</TD> - </TR> - <TR> - <TD>0x54414f07</TD><TD>"TAO\0x07"</TD> - <TD>VME bus</TD> - </TR> - <TR> - <TD>0x54414f08</TD><TD>"TAO\0x08"</TD> - <TD>NT named pipes</TD> - </TR> - <TR> - <TD>0x54414f09</TD><TD>"TAO\0x08"</TD> - <TD>HTTP-NG</TD> - </TR> - <TR> - <TD>0x54414f0A</TD><TD>"TAO\0x08"</TD> - <TD>Pipes (for collocated calls)</TD> - </TR> - </TABLE></P> - - <H4>Service Context ID</H4> - - <P>The range <CODE>0x54414f00-0x54414f0f</CODE> - (<CODE>"TAO\0x00"-"TAO\0x0f"</CODE>) is reserved for future - use. - </P> - - <H4>Component IDs</H4> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Hex Value</TH><TH>ASCII Representation</TH> - <TH>Description</TH></TR> - <TR> - <TD>0x54414f00</TD><TD>"TAO\0x00"</TD> - <TD>Server side priority for the endpoint in this profile. - The component is encoded a two shorts, the minimum and - maximum priorities (in that order). - The values correspond to the CORBA priorities defined in the - real-time CORBA spec. - The client will select the endpoint that matches its - priorities and policies. - </TD> - </TR> - </TABLE></P> - - <P>The range <CODE>0x54414f01-0x54414f0f</CODE> - (<CODE>"TAO\0x00"-"TAO\0x0f"</CODE>) is reserved for future - use. - </P> - - <H4>Vendor Minor Code ID (VMCID)</H4> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Hex Value</TH><TH>ASCII Representation</TH> - <TH>Description</TH></TR> - <TR> - <TD>0x54410000</TD><TD>"TA\x00x00"</TD> - <TD>System exceptions thrown by TAO have their higher 20 bits - set to <CODE>0x54410</CODE>, - the other 12 bits are used to describe more precisely the - cause of the exception. - The lower 4 bits encode the errno that caused the exception, - the 8 intermediate bits encode the location where the - exception was raised. - </TD> - </TR> - </TABLE></P> - - <P>The following list describes the current use of errno and - location encodings:</P> - - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Errno Value</TH><TH>Description</TH></TR> - <TR> - <TD>0x00</TD><TD>The error was not caused by a failed system - call</TD> - </TR> - <TR><TD>0x01</TD><TD>ETIMEDTOUT</TD></TR> - <TR><TD>0x02</TD><TD>ENFILE</TD></TR> - <TR><TD>0x03</TD><TD>EMFILE</TD></TR> - <TR><TD>0x04</TD><TD>EPIPE</TD></TR> - <TR><TD>0x05</TD><TD>ECONNREFUSED</TD></TR> - <TR><TD>0x06</TD><TD>ENOENT</TD></TR> - <TR><TD>0x07</TD><TD>EBADF</TD></TR> - <TR><TD>0x08</TD><TD>ENOSYS</TD></TR> - <TR><TD>0x09</TD><TD>EPERM</TD></TR> - <TR><TD>0x0A</TD><TD>EAFNOSUPPORT</TD></TR> - </TABLE></P> - - <P>Please consult the documentation for your OS for more details - about the errno meanings</P> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR><TH>Location encoding</TH><TH>Description</TH></TR> - <TR><TD>0x01</TD> - <TD>Connect failed</TD></TR> - <TR><TD>0x02</TD> - <TD>Location forward failed</TD></TR> - <TR><TD>0x03</TD> - <TD>Send request failed</TD></TR> - <TR><TD>0x04</TD> - <TD>POA in discarding state</TD></TR> - <TR><TD>0x05</TD> - <TD>POA in holding state</TD></TR> - <TR><TD>0x06</TD> - <TD>Unhandled C++ exception in server side</TD></TR> - <TR><TD>0x07</TD> - <TD>Failure while reading the reply</TD></TR> - <TR><TD>0x08</TD> - <TD>All protocols failed to parse the IOR</TD></TR> - <TR><TD>0x09</TD> - <TD>Attempt to use null pointer</TD></TR> - <TR><TD>0x0A</TD> - <TD>Error during MProfile creation</TD></TR> - <TR><TD>0x0B</TD> - <TD>Timeout while trying to establish the connection</TD></TR> - <TR><TD>0x0C</TD> - <TD>Timeout while sending the request</TD></TR> - <TR><TD>0x0D</TD> - <TD>Timeout while waiting for the reply</TD></TR> - </TABLE></P> - - <P><HR></P> - - Back to the TAO <A HREF="index.html">documentation</A>. - - <!--#include virtual="/~schmidt/cgi-sig.html" --> - </BODY> -</HTML> diff --git a/TAO/docs/compiler.html b/TAO/docs/compiler.html deleted file mode 100644 index 8b9b7fdf1fb..00000000000 --- a/TAO/docs/compiler.html +++ /dev/null @@ -1,545 +0,0 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Mozilla/4.5 [en] (X11; I; SunOS 5.5.1 sun4u) [Netscape]"> -<title>TAO IDL compiler User's Guide</title> -<!-- $Id$ --> -</head> -<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#CC0000"> - -<hr> -<h3> -TAO IDL compiler User's Guide</h3> - -<h2> Scope</h2> This document describes the options and features of -TAO IDL compiler. It is not a reference manual or tutorial on OMG -IDL. For more information on OMG IDL see the <A -HREF="http://www.omg.org/library/c2indx.html">online CORBA -specification</A> and the <A -HREF="http://www.triodia.com/staff/michi-henning.html">Advanced CORBA -Programming with C++</A> book. <P> - -<HR><P> -<h3>Generated Files</h3> - -The IDL compiler generates 9 files from each <tt>.idl</tt> file. The -file names are obtained by taking the IDL <EM>basename</EM> and -appending the following suffixes (see the list of TAO's IDL compiler -<A HREF="#options">options</A> on how to get different suffixes for -these files:) <P> - -<UL> - <LI> <EM>Client stubs</EM> -- <tt>*C.h</tt>, <tt>*C.i</tt>, and <tt>*C.cpp</tt> - <LI> <EM>Server skeletons</EM> -- <tt>*S.h</tt>, <tt>*S.i</tt>, and - <tt>*S.cpp</tt> - <LI> <EM>Server skeleton templates </EM> -- <tt>*S_T.h</tt>, <tt>S_T.i</tt>, - and <tt>*S_T.cpp</tt> -</UL> - -TAO's IDL compiler creates separate <TT>*.i</TT> and <TT>*S_T.*</TT> -files to improve the performance of the generated code. Fortunately, -you only need to <CODE>#include</CODE> the client stubs declared in -the <tt>*C.h</tt> file and the skeletons in the <tt>*S.h</tt> file in -your code. <P> - -<HR><P> -<a name="idl_env"><h3>Environment Variables</h3></a> -TAO_IDL looks for two environment variables <code>CPP_LOCATION</code> -and <code>TAO_IDL_DEFAULT_CPP_FLAGS</code>. TAO_IDL doesn't -implements its own preprocessor and it borrows the preprocessor of -the compiler of your choice to perform the preprocessing work. -On most platform TAO's makefiles can locate the compiler -automatically. However, on NT and some other situation (like cross -compiling,) you need to instruct which specific compiler to use. -<code>CPP_LOCATION</code> allows you to achieve this. It holds the -program name of the compiler that TAO_IDL uses. This should be a full -pathname if the compiler is not within your <code>$PATH</code>. - -TAO_IDL also defines a set of default command line options passed to -the preprocessor depending on which platform TAO_IDL is compiled. The -environment variable <CODE>TAO_IDL_DEFAULT_CPP_FLAGS</CODE> allows you -to alter the command line optiona passed to the preprocessor. You can -use it to alter the default options for the preprocessor and specify -things like include directories and how the preprocessor is invoked. -Two flags that won't get overwritten by the environment variable are -<code>-DIDL</code> and <code>-I.</code>. They are always passed to -the preprocessor. - -If your IDLs need to include <code><orb.idl></code>, then you need to -define either/both <code>ACE_ROOT</code> or/and <code>TAO_ROOT</code>. If you -already have <CODE>ACE_ROOT</CODE> defined, TAO_IDL can figure -<CODE>TAO_ROOT</CODE> out if your ACE/TAO was installed using default directory -structure, otherwise, you'll need to define <code>TAO_ROOT</code>. - -<HR><P> -<h3>Operation Demuxing Strategies</h3> - -The server skeleton can use different demuxing strategies to match the -incoming operation with the correct operation at the servant. TAO's -IDL compiler supports perfect hashing, binary search, and dynamic -hashing demuxing strategies. By default, TAO's IDL compiler tries to -generate perfect hash functions, which is generally the most <A -HREF="http://www.cs.wustl.edu/~schmidt/COOTS-99.ps.gz">efficient and -predictable operation demuxing technique</A>. To generate perfect -hash functions, TAO's IDL compiler uses <a -href="http://www.cs.wustl.edu/~schmidt/gperf.ps.gz">gperf </a>, which -is a general-purpose perfect hash function generator. <P> - -To configure TAO's IDL compiler to support perfect hashing please do -the following: - -<ul> - <LI>Enable <CODE>ACE_HAS_GPERF</CODE> when building ACE and TAO. - This macro has been defined for the platforms where <CODE>gperf</CODE> - has been tested, which includes most <A - HREF="http://www.cs.wustl.edu/~schmidt/ACE-versions-i.html">platforms</A> - that ACE runs on. <P> - - <li>Build the <CODE>gperf</CODE> in $ACE_ROOT/apps/gperf. This build - also leaves a copy/link of the gperf program at the $ACE_ROOT/bin - directory.<P> - - <li>Set the environment variable $ACE_ROOT appropriately or add - $ACE_ROOT/bin to your search path. <P> - - <li>Use the <CODE>-g</CODE> option for the TAO IDL compiler or set - your search path accordingly to install <CODE>gperf</CODE> in a - directory other than $ACE_ROOT/bin. -</ul> - -Note that if you can't use perfect hashing for some reason the next -best operation demuxing strategy is binary search, which can be -configured using TAO's IDL compiler <A HREF="#options">options</A>.<P> - -<hr><p> -<h3><a name="collocation-stubs">Collocation Strategies</a></h3> - -TAO_IDL can generate collocated stubs using two different collocation -strategies. It also allows you to supress/enable the generation of -the stubs of a particular strategy. To gain great flexibility at -run-time, you can gereate stubs for both collocation strategies -(using both '<a href="#Gp"><code>-Gp</code></a>' and '<a -href="#Gd"><code>-Gd</code></a>' flags at the same time) and defer the -determination of collocation strategy until run-time. On the other -hand, if you want to minimize the footprint of your program, you might -want to pre-determine the collocation strategy you want and only -generate the right collocated stubs (or not generating any at all using -both '<a href="#Sp"><code>-Sp</code></a>' and '<a -href="#Sd"><code>-Sd</code></a>' flags at the same time if -it's a pure client.) See our <a -href="http://www.cs.wustl.edu/~schmidt/C++-report-col18.ps.gz">collocation -paper</a> for a detail discussion on the collocation support in -TAO.<p> - - -<HR><P> -<h3><A NAME="options">TAO's IDL Compiler Options</A></h3> - -TAO's IDL compiler invokes your <tt>C</tt> (or <tt>C++</tt>) -preprocessor to resolve included IDL files. It receives the common -options for preprocessors (such as <tt>-D</tt> or <tt>-I</tt>). It -also receives other options that are specific to it. <P> - -<table BORDER=2 CELLSPACING=2 CELLPADDING=0 > - <tr> - <th>Option</th> - <th>Description</th> - <th>Remark</th> - </tr> - <tr><a NAME="u"> - <td><tt>-u</tt></td> - - <td>The compiler prints out the options that are given below and exits - clean </td> - <td> </td> - </tr> - - <tr> <a NAME="V"> - <td><tt>-V</tt></td> - - <td>The compiler printouts its version and exits</td> - <td> </td> - </tr> - - <tr><a name="Wb"> - <td><tt>-Wb,</tt><i>option_list</i></EM</TD></td> - - <td>Pass options to the TAO IDL compiler backend.</td> - <td> </td> - </tr> - - <tr><a name="export_macro"> - <td></td> - - <td><tt>export_macro=</tt><i>macro_name</i></td> - - <td>The compiler will emit <i>macro_name</i> right after each <tt>class</tt> - or <tt>extern</tt> keyword, this is needed for Windows/NT that requires - special directives to export symbols from DLLs, usually the definition - is just a space on unix platforms. </td> - </tr> - - <tr><a name="export_include"> - <td></td> - - <td><tt>export_include=</tt><i>include_path</i></td> - - <td>The compiler will generate code to include <i>include_path</i> at the - top of the client header, this is usually a good place to define the export - macro.</td> - </tr> - - <tr><a name="pch_include"> - <td></td> - - <td><tt>pch_include=</tt><i>include_path</i></td> - - <td>The compiler will generate code to include <i>include_path</i> at the - top of all TAO IDL compiler generated files. This can be used with a - precompiled header mechanism, such as those provided by Borland - C++Builder or MSVC++.</td> - </tr> - - <tr><a name="E"> - <td><tt>-E</tt></td> - - <td>Only invoke the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="Wp"> - <td><tt>-Wp,</tt><i>option_list</i></EM</TD></td> - - <td>Pass options to the preprocessor.</td> - <td> </td> - </tr> - - <tr><a name="D"> - <td><tt>-D</tt><i>macro_definition</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="U"> - <td><tt>-U</tt><i>macro_name</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="I"> - <td><tt>-I</tt><i>include_path</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="A"> - <td><tt>-A</tt><i>assertion</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="Y"> - <td><tt>-Y</tt></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="H perfect_hash"> - <td><tt>-H perfect_hash</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses perfect - hashed operation demuxing strategy, which is the default strategy. Perfect - hashing uses <a href="http://www.cs.wustl.edu/~schmidt/gperf.ps.gz">gperf - </a>program, - to generate demuxing methods. </td> - <td> </td> - </tr> - - <tr><a name="H dynamic_hash"> - <td><tt>-H dynamic_hash</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses dynamic - hashed operation demuxing strategy. </td> - <td> </td> - </tr> - - <tr><a name="H binary_search"> - <td><tt>-H binary_search</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses binary - search based operation demuxing strategy. </td> - <td> </td> - </tr> - - <tr><a name="H linear_search"> - <td><tt>-H linear_search</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses linear - search based operation demuxing strategy. Note that this option is for testing purposes only and should not be used for production code since it's inefficient.</td> - <td> </td> - </tr> - - - <tr><a name="in"> - <TD><TT>-in</TT></TD> - <TD> To generate #include statements with <>'s for the standard - include files (e.g. tao/corba.h) indicating them as non-changing - files</TD> - <td> </td> - </TR> - - - <TR><A NAME="ic"> - <TD><TT>-ic</TT></TD> - <TD> To generate #include statements with ""s for changing - standard include files (e.g. tao/corba.h). </TD> - <td> </td> - </TR> - - <tr><a name="g"> - <td><tt>-g</tt></td> - - <td>To specify the path for the perfect hasing program (GPERF). Default - is $ACE_ROOT/bin/gperf. </td> - <td> </td> - </tr> - - <tr><a name="o"> - <td><tt>-o</tt></td> - - <td>To specify the output directory to IDL compiler as to where all the - IDL-compiler-generated files are to be put. By default, all the files are - put in the current directory from where <tao_idl>is called. </td> - <td> </td> - </tr> - - <tr><a name="hc"> - <td><tt>-hc</tt></td> - - <td>Client's header file name ending. Default is "C.h".</td> - <td> </td> - </tr> - - <tr><a name="hs"> - <td><tt>-hs</tt></td> - - <td>Server's header file name ending. Default is "S.h".</td> - <td> </td> - </tr> - - <tr><a name="hT"> - <td><tt>-hT</tt></td> - - <td>Server's template header file name ending. Default is "S_T.h".</td> - <td> </td> - </tr> - - <tr><a name="cs"> - <td><tt>-cs</tt></td> - - <td>Client stub's file name ending. Default is "C.cpp".</td> - <td> </td> - </tr> - - <tr><a name="ci"> - <td><tt>-ci</tt></td> - - <td>Client inline file name ending. Default is "C.i".</td> - <td> </td> - </tr> - - <tr><a name="ss"> - <td><tt>-ss</tt></td> - - <td>Server skeleton file name ending. Default is "S.cpp".</td> - <td> </td> - </tr> - - <tr><a name="sT"> - <td><tt>-sT</tt></td> - - <td>Server template skeleton file name ending. Default is "S_T.cpp".</td> - <td> </td> - </tr> - - <tr><a name="si"> - <td><tt>-si</tt></td> - - <td>Server inline skeleton file name ending. Default is "S.i".</td> - <td> </td> - </tr> - - <tr><a name="st"> - <td><tt>-st</tt></td> - - <td>Server's template inline file name ending. Default is "S_T.i".</td> - <td> </td> - </tr> - - <tr><a name="t"> - <td><tt>-t</tt></td> - - <td>Temporary directory to be used by the IDL compiler. Default : - Resolve ACE_DEFAULT_TEMP_DIR_ENV. If it is not defined, choose - /tmp/. - </td> - <td> </td> - </tr> - - <tr><a name="Cw"> - <td><tt>-Cw</tt></td> - - <td>Output a warning if two identifiers in the same scope differ in - spelling only by case (default for now).</td> - <td> </td> - </tr> - - <tr><a name="Ce"> - <td><tt>-Ce</tt></td> - - <td>Output an error if two indentifiers in the same scope differ in - spelling only by case. Default output is warning (for now).</td> - - <td>Since there is at least one OMG IDL file (sfp.idl, part of the - AVStreams specification) that is inconsistent with its own spelling - rule, we have made a warning the default output until the issue - is resolved.</td> - </tr> - - <tr><a name="Gc"> - <td><tt>-Gc</tt></td> - - <td>Generate stubs and skeletons using compiled marshaling </td> - <td> </td> - </tr> - - <tr><a name="Gi"> - <td><tt>-Gi</tt></td> - - <td>Generate stubs and skeletons using interpretive marshaling (default - for now) </td> - <td> </td> - </tr> - - <tr><a name="Ge flag"> - <td><tt>-Ge </tt><i>flag</i></td> - - <td>If the value of the flag is 0, tao_idl will generate code that - will use native C++ exceptions. If the value of the flag is 1, - tao_idl will generate code that will use environment variable for - passing exceptions </td> - <td> </td> - </tr> - - <tr><a name="Gp"> - <td><tt>-Gp </tt></td> - - <td>Generated collocated stubs that use <code>Thru_POA</code> collocation strategy (default)</td> - <td> </td> - </tr> - - <tr><a name="Gd"> - <td><tt>-Gd </tt></td> - - <td>Generated collocated stubs that use <code>Direct</code> collocation strategy</td> - <td> </td> - </tr> - - <tr><a name="Gt"> - <td><tt>-Gt</tt></td> - - <td>Generate optimized TypeCodes (unimplemented as yet)</td> - <td> </td> - </tr> - - <tr><a name="Gv"> - <td><tt>-Gv</tt></td> - - <td>Generate code that suppports Object-By-Value</td> - <td> </td> - </tr> - - <tr> - <td>-<tt>GI</tt></td> - - <td>Generate templates files for the servant implementation </td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIh </tt><i>arg</i></td> - - <td>Servant implemenation header file name ending</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIs </tt><i>arg</i></td> - - <td>Servant implemenation skeleton file name ending</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIb </tt><i>arg</i></td> - - <td>Prefix to the implementation class names</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIe </tt><i>arg</i></td> - - <td>Suffix to the implementation class names</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIc </tt><i>arg</i></td> - - <td>Generate copy constructors in the servant implementation template files</td> - <td> </td> - </tr> - - <tr><a name="Sa"> - <td><tt>-Sa</tt></td> - - <td>Suppress generation of the Any operators</td> - <td> </td> - </tr> - - <tr><a name="Sp"> - <td><tt>-Sa</tt></td> - - <td>Suppress generation of collocated stubs that use <code>Thru_POA</code> collocation strategy</td> - <td> </td> - </tr> - - <tr><a name="Sd"> - <td><tt>-Sd</tt></td> - - <td>Suppress generation of collocated stubs that use <code>Direct</code> collocation strategy (default)</td> - <td> </td> - </tr> - - <tr><a name="St"> - <td><tt>-St</tt></td> - - <td>Suppress generation of the TypeCodes</td> - <td> </td> - </tr> -</table> <P> - -<P><HR><P> -Back to the TAO <A HREF="index.html">documentation</A>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> - -</body> -</html> diff --git a/TAO/docs/components.html b/TAO/docs/components.html deleted file mode 100644 index 5a1d34631d0..00000000000 --- a/TAO/docs/components.html +++ /dev/null @@ -1,44 +0,0 @@ -<HTML> - <HEAD> - <META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> - <TITLE>TAO Component Documentation</TITLE> - </HEAD> - -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<HR> - <H3 ALIGN=CENTER>Component Documentation</H3> - - <P>The following documentation is available on certain TAO components:</P> - - <UL> - <LI><A HREF="Options.html">Options</A> ­ describes the - options available to customize various components within TAO. - These customizations can be done by an end-user and do not - require C++ programming.<P> - - <li><a href="configurations.html">Configuration</a> ­ - describes how to mix and match component <a - href="Options.html">options</a> to customize - how TAO processes requests. For example, this - document explains how to configure TAO to process - all request in one thread, each request in a separate thread, or each connection - in a separate thread, <em>etc.</em><P> - - <LI> Mapping of all <A - HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/">TAO files</A> - into a manageable set of <A -HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/TAO-inheritance.ps.gz">inheritance -hierarchies</A>. <P> - </UL> - </BODY> - -<P><HR><P> -Back to the TAO <A HREF="index.html">documentation index</A>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> - -</HTML> diff --git a/TAO/docs/configurations.html b/TAO/docs/configurations.html deleted file mode 100644 index a4466563beb..00000000000 --- a/TAO/docs/configurations.html +++ /dev/null @@ -1,770 +0,0 @@ -<!-- $Id$ --> -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> - -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]"> -<title>Configuring TAO's Components</title> -</head> - -<body text="#000000" bgcolor="#FFFFFF" link="#000FFF" vlink="#FF0F0F"> - -<hr> -<h3> -Configuring TAO's Components</h3> - -<h3> Overview</h3> - -<p> As described in the <a href="Options.html">options</a> -documentation, various components in TAO can be customized by -specifying options for those components. This document illustrates -how to combine these options in order to affect ORB behavior and -performance, particularly its <a -href="http://www.cs.wustl.edu/~schmidt/CACM-arch.ps.gz">concurrency -model</a>. </p> - -<p> TAO configures itself using the <a -href="http://www.cs.wustl.edu/~schmidt/Svc-Conf.ps.gz">ACE -Service Configurator</a> framework. Thus, options are specified in the -familiar <tt>svc.conf</tt> file (if you want to use a different file -name, use the <tt><a href="Options.html#svcfonf">-ORBsvcconf</a></tt> -option). You can also setup default configurations for your programs. -Please see the <a href="#programming">Programming Considerations</a> -for more detailed discussion on this.</p> - -<hr> -<h3> -Roadmap</h3> - -<blockquote>Details for the following configurations are provided. -<ul> - <li><b><a href="#comp">Configurating key components</a>:</b></li> - - <ul> - <li><a href="#concurrency">Server Concurrency Strategy.</a></li> - - <li><a href="#orb">Number of ORBs.</a></li> - - <!-- <li><a href="#orb_resources">ORB resources.</a></li> --> - - <li><a href="#poa">POA.</a></li> - - <li><a href="#coltbl">Collocation Table.</a></li> - - <li><a href="#profile">Forwarding Profile</a></li> - - <li><a href="#orbsvcs">orbsvcs Library</a></li> - </ul> - - <li> - <b><a href="#examples">Configuration examples</a></b></li> - - <ul> - <li><a href="#reactive">Single-threaded, reactive model.</a></li> - - <li><a href="#tpc">Single ORB, multiple threads, thread-per-connection - model.</a></li> - - <li><a href="#multiorb">Multiple threads, multiple ORBs, - reactive model.</a></li> - - <li><a href="#multiorb-tpc">Multiple threads, multiple ORBs, - thread-per-connection model.</a></li> - - <li><a href="#tpool">Multiple threads, thread-pool model.</a></li> - - <li><a href="#multiorb-tpool">Multiple threads, - ORB-per-thread, thread-pool reactive model.</a></li> - - <li> - Each configuration has the following information:</li> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="70%"> - <tr> - <th align=left>Typical Use</th> - - <td>A brief description of the scenario and - its typical use.</td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>The number of threads used by - ORB-related activities.</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>Identifies the creator of the threads - discussed above.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>Describes what task is undertaken for - each thread.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td>Specifies the options for each service in order to - utilize this configuration.</td> - </tr> - </table> - </ul> - - <li><b><a href="#programming">Programming considerations</a></b> - - <li><b><a href="#homogenous">Configuration for homogenous systems</a></b></li> - - <ul> - <li><a href="#homogenous_compile">Compile time options</a></li> - - <li><a href="#homogenous_runtime">Runtime time</a></li> - </ul> -</ul> -</blockquote> - -<hr> -<h3> -<a NAME="comp"></a>Configuring Key ORB Components</h3> - -<ul> - <li><a name="orb"><b>Number of ORBs</b> -- </a></li> - TAO can assign multiple endpoints to an ORB. Therefore, - it is not necessary to create multiple ORBs to accept - requests from multiple endpoints. However, multiple ORBs can be - used to support different policies within the same process, - <EM>e.g.</EM>, handling requests in different thread - priorities. Multiple ORBs are most commonly used in the "ORB - per-priority" pattern to avoid priority inversion in real-time - system. <p> - - <li><a NAME="concurrency"></a><b>Server concurrency strategy</b> -- - The default server strategy factory provided by down support two - different concurrency strategy. It can be specified by adding - the "<tt>-ORBconcurrency</tt>" flag in the <code><a - href="Options.html#orb_concurrency"> Server_Strategy_Factory - </a></code> entry of the <code>svc.conf</code> file. This - specifies the concurrency strategy an ORB uses. This strategy - is orthogonal the the number of ORBs or threads that are - configured in a server process. </li><P> - - <ul> - <li><tt>reactive</tt>: The ORB handles requests reactively, - i.e., the ORB runs in one thread and service multiple - requests/connections simultaneously using the - <A - HREF="http://www.cs.wustl.edu/~schmidt/ACE-papers.html#reactor"> - ACE_Reactor</A>, which uses <tt>select</TT> or a similar - event demultiplexing mechanism supported by the - platform. </li> <P> - - <li><tt>thread-per-connection</tt>: The ORB handles new - connections by spawning a new thread whose job is to - service requests coming from the connection.</li> - </UL><P> - - <li><a name="orb"><b>Thread Pools</b></a></li> -- - TAO supports several types of thread pools. <P> - - <ul> - <li><tt>reactive</tt>: In this approach, each thread - in the thread pool has an ORB that accepts and processes - requests reactively. <P> - - <li><P><tt>leader/follower</tt>: In this model, the user must - create several threads, all of which invoke - <CODE>ORB::run</CODE>, the ORB will select one of the threads - to wait for incoming requests. - This thread is called the leader thread and will process the - first request that arrives to the ORB, but before - doing so the ORB will selects another thread in the pool to - become the leader. - In other words the threads in the pool take turns to - process the events. - </p> - <p> - Notice that this configuration requires the - <CODE>ACE_TP_Reactor</CODE>, i.e. - you must use the <CODE>-ORBReactorType tp</CODE> in the - configuration file. - </p> - </li> - - </UL><P> - - <!-- - <li><a NAME="orb_resources"></a><b>ORB resources</b> -- - - <ul> - <li><tt>global</tt>: All threads using the ORB access to - the a set of global per-ORB resources. The same set of - pre-ORB resources are shared by all threads accessing the - ORB. Notice that if you have more than one ORB, each ORB - owns its own global resources. - - <li><tt>tss</tt>: Each thread accessing an ORB gets its own - set of thread-specific resources for the ORB. - - <!-- @@ What about resource inheritance? - -> - </ul><P></li> --> - - <li><a NAME="coltbl"></a><b>Collocation Table</b> -- An ORB can have - several listening endpoints. If there are several ORBs in a - process and a global collocation table is used, then all objects - in the same process are considered collocated. If not, only - objects reside in the same <em>ORB</em> are considered - collocated. You can control the usage of global collocation - table by passing the <code><a href="Options.html#-ORBCollocation"> - -ORBCollocation </a></code> flag as an argument of <code> - ORB_init </code> (most often thru the command line flags.) <p> - - <li> <a NAME="profile"></a><b>Forwarding Profile</b> -- - When multiple threads using the same - <tt>CORBA::Object</tt> and using forwarding, it is necessary to - protect the forwarding <tt>Profile</tt>, which is part of the - CORBA::Object, against multiple access. Therefore a mutex lock - is used by default to ensure proper access. <P> - - Using the switch <tt><a href="Options.html#-ORBProfileLock"> - -ORBprofilelock </a></tt> this policy can be deactivated - specifying <tt>-ORBprofilelock null</tt>. - The primary reason for doing this is to improve performance - when no forwarding is used or no multithreading with access to - shared <tt>CORBA::Object</tt>'s. Using a null mutex reduces - the overhead compared with using a regular mutex - lock.</li><P> - - <li> <a NAME="orbsvcs"></a><b>orbsvcs Library</b> -- By default, the - TAO orbsvcs library contains all of the services that TAO - currently supports. To reduce build time and library size, you - can exclude unused services. To do that, define a - <tt>TAO_ORBSVCS</tt> variable using one of these - approaches:</li><P> - - <ol> - <li>In your - <tt>$(ACE_ROOT)/include/makeinclude/platform_macros.GNU - </tt> file, - - <li>On the make command line, <i>e.g.</i>, <tt>make - TAO_ORBSVCS=Event</tt>, or - - <li>Set (and export) a <tt>TAO_ORBSVCS</tt> environment variable. - </ol><p> - - Please see the <code><a - href="../orbsvcs/orbsvcs/Makefile">ORBSVCS - Makefile</a></code> for the default setting of - <code>TAO_ORBSVCS</code>.<p> - - Please note that the Naming Service will always be built, even - if Naming is not specified in <code>TAO_ORBSVCS</code>. That's - because many examples, tests, and presumably applications use it.<p> -</ul> - -<hr> -<h3> -<a NAME="examples"></a>Configuration Examples</h3> - -The following are common ORB configurations used by TAO applications.<P> - -<ul> - <li> - <a NAME="reactive"></a>Single-threaded, reactive model.</li><P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" > - <tr> - <th ALIGN=LEFT>Typical Use</th> - - <td>This is the default configuration of TAO, where one - thread handles requests from multiple clients via a - single Reactor. It is appropriate when the requests (1) - take a fixed, relatively uniform amount of time and (2) - are largely compute bound. </td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>1</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>OS or whoever creates the main ORB thread in a process.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>The single thread processes all connection requests and - CORBA messages.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td>The default settings should work just fine. However, - you can apply the following options to improve performance:<br> - <tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - select_st</tt>, <tt>-ORBInputCDRAllocator null</tt> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency reactive</tt> (default), - <tt>-ORBPOALock null</tt></td> - <br><tt>TAO_Client_Strategy_Factory</tt>: - <tt>-ORBConnectorLock null</tt> - </td> - </tr> - </table> - - <P>Check out the <tt><a href="../examples/Simple/grid/">Grid</a></tt> - for an example of this configuration. <P> - - <li> <a NAME="tpc"></a>Single ORB, multiple threads, thread-per-connection - model.</li> <P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" > - <tr ALIGN="LEFT"> - <th align=left>Typical Use - </th> - - <td>This configuration spawns a new thread to serve requests - from a new connection. This approach works well when - there are multiple connections active simultaneously and - each request-per-connection may take a fair amount of - time to execute. - </td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>1 thread for the ORB, plus 1 thread for each connection.</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>Programmer must set up the main thread which the ORB - lives. The ORB is responsible to create new threads upon - new connections.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>The main thread handles new connections and spawns new - threads for them. Other threads handle requests for - established connections.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td><tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - select_mt</tt> (default) or other thread-safe platform specific - reactors.<br> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency thread-per-connection</tt></td> - </tr> - </table> - <P> - <tt><a href="../performance-tests/Cubit/TAO/IDL_Cubit/">IDL_Cubit</a></tt> - is a good example on using <i>multiple threads, thread-per-connection</i> - configuration.<P> -<li> - <P>Multiple threads, multiple ORB, reactive model.<a NAME="multiorb"></a></li><P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%"> - <tr> - <th align=left>Typical Use</th> - - <td>In this configuration, there are multiple ORBs in a - process with multiple threads. Each thread handles requests - reactively. It's good for hard real-time applications that - require different thread priorities for the various - ORBs.</td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>One thread for each ORB.</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>The main process (thread).</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>Service the requests from associating ORB.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td><tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - select_mt</tt> (default) or other thread-safe platform specific - reactors.<br> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency reactive</tt></td> - </tr> -</table> -<P> - -<li>Multiple threads, multiple ORBs, thread-per-connection model.<a - NAME="multiorb-tpc"></a></li><P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%"> - <tr align="left"> - <th align=left>Typical Use - </th> - - <td>This approach provides a range of thread priorities plus connections - that don't interfere with each others.</td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>One thread for each ORB, plus one thread for each connection.</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>Main threads creates threads running ORBs. They, in turns, - create connection handling threads.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>There are threads running ORB's event loops which handle - connection requests and handler threads which service - requests form establiched connections.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td><tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - select_mt</tt> (default) or other thread-safe platform specific - reactors.<br> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency thread-per-connection</tt></td> - </tr> -</table> - -<P> -<tt><a href="../performance-tests/Cubit/TAO/MT_Cubit/">MT_Cubit</a> -</tt> is a good example on using <i>multiple threads, -multiple ORBs, and thread-per-connection</i> configuration.<P> -<li> - <a NAME="tpool"></a>Multiple threads, single ORB, thread-pool model.</li><P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" > - <tr> - <th align=left>Typical Use</th> - - <td>This model implements a highly optimized thread pool that leverages - context switching, and thread creation costs. In this - model, the programmer is responsible of spawning a group - of threads, start up the ORB and then instruct all the threads - to run the ORB event loop. When a request comes in, one - of these waiting threads in the pool will handle the - request.</td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>Thread for the ORB, plus the number of threads used by the thread pool.</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>Pre-spawned by the main thread.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>Blocking on the reactor to wait for its turn to handle a request.</td> - </tr> - - <tr> - <th align=left>Options</th> - - <td><tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - tp</tt>.<br> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency reactive</tt></td> - </tr> - </table> - -<P><li> - Multiple threads, multiple ORBs, thread-pool model.<a NAME="multiorb-tpool"></a> -</li><P> - - <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" > - <tr> - <th align=left>Typical Use</th> - - <td>This model incorporates the advantage of using thread-pool - while allowing hard real-time system to handle requests in - different priority.</td> - </tr> - - <tr> - <th align=left>Number of Threads</th> - - <td>One thread for each ORB, plus the total number of threads in all thread pools</td> - </tr> - - <tr> - <th align=left>Thread Creator</th> - - <td>Pre-spawned by the main thread.</td> - </tr> - - <tr> - <th align=left>Thread task</th> - - <td>Handle incoming request for the ORB event loop it is - waiting on.</td> - </tr> - <tr> - <th align=left>Options</th> - - <td><tt>TAO_Resource_Factory</tt>: <tt>-ORBReactorType - tp</tt>.<br> - <br><tt>TAO_Server_Strategy_Factory</tt>: - <tt>-ORBconcurrency reactive</tt></td> - </tr> -</table> -</ul> - -<hr> -<h3> -Programming Considerations<a NAME="programming"></a></h3> - -There are several ways to pass option flags into TAO's -components. <P> - -<ul> - - <li><p>The plain vanilla approach is do nothing. All TAO components - use their <a - href="Options.html">default settings</A>.</p> - - <li><p>The most common use case is to use a file called - <code>svc.conf</code>. On most platforms, TAO programs - automatically search and read in the file. The disadvantage of - this approach is you always need a <code>svc.conf</code> file if - you want to do use non-default configuration.</p> - - <li><p>You can use <code>-ORBsvcconf <em>filename</em></code> to use - a config file that is not called <code>svc.conf</code>. - Specifying <code>-ORBsvcconf</code> exclude the reading of - default <code>svc.conf</code> file.</p> - - <li><p>If you don't want the application users to worry about - setting up or knowing about <code>svc.conf</code> files, you can - call <code>TAO_Internal::default_svc_conf_entries()</code> - before calling the first <code>ORB_init()</code> in your program - to set up the default svc.conf entries. In this case, if a TAO - application cannot find a svc.conf file, it will configure TAO's - components using the default settings. You can still use a - <code>svc.conf</code> file or use <code>-ORBsvcconf</code> - option to tune the program.<P> - - <li><p>TAO programs evaluate the configuration settings in the following - order,</p> - - <ol> - <li>File specified in <code>-ORBsvcconf</code> command-line - option, if one exist. Otherwise, the - <code>svc.conf</code> in the start-up directory will be - evaluated, if one exist. - <li>Default entries set by - <code>TAO_Internal::default_svc_conf_entries()</code>, if - ones exist. - <li>Default configuration as specified in <a - href="Options.html">this document</a>. - </ol> - - <p>Notice that the first encountered component settings are - always the ones take effect. For example, if you set the entries - for <code>Resource_Factory</code> and - <code>Server_Strategy_Factory</code> using - <code>TAO_Internal::default_svc_conf_entries()</code> in a - program and you also have a file called <code>svc.conf</code> - which has an entry for <code>Resource_Factory</code>. This - program will use the entry for <code>Resource_Factory</code> in - the <code>svc.conf</code> file, the entry for - <code>Server_Strategy_Factory</code> set in the program, and the - in-stock <code>Client_Strategy_Factory</code> that TAO defines. <P> - - <li><p>Some platforms do not support reading of <code>svc.conf</code> - files or you would rather not to use the feature. In this case, - you must define <code>TAO_PLATFORM_SVC_CONF_FILE_NOTSUP</code> - in your ACE <code>config.h</code> file and recompile TAO - library. In this case, a TAO program will not try to search for - the default <code>svc.conf</code> file. However, if platform - support, you can still use <code>-ORBsvcconf</code> to change - the program behavior temporarily.</p> - - <p>On these platform, you can alter the default settings for - TAO components by defining the following macros in your - <code>config.h</code> file:</p> - - <ul> - <li><code>TAO_DEFAULT_RESOURCE_FACTORY_ARGS</code> - <li><code>TAO_DEFAULT_SERVER_STRATEGY_FACTORY_ARGS</code> - <li><code>TAO_DEFAULT_CLIENT_STRATEGY_FACTORY_ARGS</code> - </ul> - - <p>The ACE Makefiles <code>fakesvcconf</code> flag can be - used to define <code>TAO_PLATFORM_SVC_CONF_FILE_NOTSUP</code>. - To define that macro, just add <code>fakesvcconf=1</code> to - your <code>make</code> invocation. - - <p>See <a href="../tao/orbconf.h"><code>orbconf.h</code></a> for - an example. -</ul> - -<hr> -<h3> -Configuration for homogenous systems<a NAME="homogenous"></a></h3> - -<ul> - <LI><b>Compile-time options</b><a NAME="homogenous_compile"></a> - <p>Many real-time applications run on homogenous environments, TAO (and - ACE) can take advantage of this fact by simplifying the server side demarshaling; - to enable this feature you have to edit the <tt>$ACE_ROOT/ace/OS.h</tt> - file and enable the macro <font size=-1>ACE</font><tt>_DISABLE_SWAP_ON_READ</tt>. - <p>In this systems it is also common that server and the client startup - and shutdown simultaneously, in those circumstances there is no need to - check the timestamps in the POA, another macro (<tt>POA_NO_TIMESTAMP</tt>) - can be used for this purpose. - <p>Users running in embebbed systems may also need to modify the default - options for TAO, the macros <tt>TAO_DEFAULT_RESOURCE_FACTORY_ARGS</tt>, - <tt>TAO_DEFAULT_CLIENT_STRATEGY_FACTORY_ARGS</tt> and <tt>TAO_DEFAULT_SERVER_STRATEGY_FACTORY_ARGS</tt> - can be used for those purposes. If the footprint size is an issue users - may consider writing custom strategy factories that only create the right - strategies, this eliminates the parsing code for the different options. - - <p> - <LI><b>Run-time options</b><a NAME="homogenous_runtime"></a> - <p>If the only ORB running is TAO and there is no need to be IIOP interoperable - the option <tt>-ORBgioplite</tt> can be used to reduce the message size - and the processing time. - <p>Some embedded systems run without the benefit of a DNS server, in that - case they can use the <tt>-ORBdotteddecimaladdresses</tt> option; the ORB - will avoid the use of hostnames in the profiles it generates, thus clients - don't need to do any name resolution. The compile-time define <tt>TAO_USES_DOTTED_DECIMAL_ADDRESSES</tt> - in <tt>$TAO_ROOT/tao/orbconf.h</tt> to make this the default behavior. -</ul> - -<hr> -<h3>Configuration Suggestions</h3> - -Choosing the right configuration is hard and, of course, depends on your -application. In the following section we will attempt to describe some -motivations for features in TAO, hopefully that can guide you through the -choice of your configuration options. -<ul> - - <LI><b>ORB-per-thread</b> -- The main motivation behind this options is to - minimize priority invertion, since threads share no ORB resources no locking - is required and thus, priority is preserved in most cases (assuming proper - support from the OS). If you are not too concerned about priority inversion - try to use a single ORB, using ORB-per-thread has some tradeoffs (like - calling ORB_init on each thread, activation of a servant is more complicated, - etc.) Some of the problems, can be minimized, but they require even more - careful analysis. - <p>As the reader will note this is a delicate configuration option, the - rule of thumb should be <b>not</b> to use ORB-per-thread unless it is really - required. <P> - - <li> - - <b>Collocation tables</b> -- Why would an application not want to - use the global collocation table? Because a collocated method - invocation is run in the client's thread-of-control. If objects - are to serve requests only at a well - known priority the application can be configured with the - ORB-per-thread option, and the object is activated only in the thread - (ORB) corresponding to the desired priority. But using a global table - would subert the priority assignment (because calls would run at the - priority of the client).</li><P> - - <li> <b>Single-threaded vs. Multi-threaded Connection Handlers</b> - -- The - <tt>Client_Connection_Handler</tt> is the component in TAO that writes - the requests to the underlying transport socket; this is also the - component that reads the response back from the server.</li> - - <p> - - While waiting for this response new requests to the local ORB can - arrive, this is the so-called nested upcall support. TAO supports two - mechanisms for handling nested upcalls, the default uses the - leader-follower model to allow multiple threads to wait on a single - reactor for several concurrent requests; sometimes this configuration - can be an overkill, if only one thread is using a reactor at the same - time a lighter weight implementation can be used. <p>This - configuration is controled by the <tt>-ORBclientconnectionhandler</tt> - option, good opportunities to use this option are:<P> - - <ul> - <li> Single threaded servers</li> - - <li> Servers running in ORB-per-thread mode (pseudo single - threaded.)</li> - - <li> Pure clients that will never receive a request</li> - </ul><P> - -<li> - <b>Allocator for input CDR streams</b> -- Normally the application has no - access to this buffer, and it is only used on the demarshaling of arguments - (or results). It is almost always better to use the "<tt>-ORBinputcdrallocator - null</tt>" option since it will allocate memory from a thread specific allocator - and it will not need locks to manage that memory.</li> - - <p>In some cases the user <i>may</i> gain access to the CDR stream - buffer: TAO makes no copies when demarshaling octet sequences, instead - the octet sequence simply points to the CDR buffer, since the octet - sequence does not own this buffer a copy must be made if the user - wants to keep the buffer after the upcall. - - <p>The user can, however, increase the reference count on the CDR - stream buffer, thus allowing her to extend the lifetime of this - buffer. Still passing this buffer to another thread and attempting to - release it in that thread will result in some memory leak or - corruption. Users willing to use this feature of TAO can still do so, - <b>if</b> they use a global allocator for their input CDR stream, but - that will introduce extra locking on the critical path. <p>As the - reader can see this is an option that has limited applicability and - requires careful consideration of the tradeoffs involved. -</ul> - -<hr> -<p>Back to the TAO <a href="components.html">components documentation</a>.<!--#include virtual="/~schmidt/cgi-sig.html" --> -</body> -</html> diff --git a/TAO/docs/ec_options.html b/TAO/docs/ec_options.html deleted file mode 100644 index 06c8c54d8ed..00000000000 --- a/TAO/docs/ec_options.html +++ /dev/null @@ -1,355 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - <head> - <title>Real-time Event Channel Configuration</title> - <!-- $Id$ --> - </head> - - <body> - <CENTER> - <h1>Real-time Event Channel Configuration</h1> - </CENTER> - - <H3>Overview</H3> - - <P>The new implementation of the real-time event channel uses a - factory to build all the objects and strategies it requires. - The factory can be dynamically loaded using ACE Service - Configurator, this is extremely convenient because the factory - can also parse options in the Service Configurator script file. - </P> - - <P>The current implementation provides a default implementation - for this Factory, this document describes the options used by - this default implementation. - </P> - - <H3>The configuration file</H3> - - <P>The real-time event channel uses the same service configurator - file that the ORB uses, the default name for this file is - <CODE>svc.conf</CODE>, but the ORB option - <CODE>-ORBSvcConf</CODE> can be used to override this. - The format of the file is described in detail in - the service configurator documentation, but the relevant section - for the event channel looks like this: - </P> - -<PRE> -# Comments go here... -# More comments if you want to... -static EC_Factory "-ECFiltering basic ....." -</PRE> - - <P>All the event service factory options start with - <CODE>-EC</CODE></P> - - - <H3>The options</H3> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <!-- <TR NAME="ECDispatching"> --> - <TR> - <TD><CODE>-ECDispatching</CODE> - <EM>dispatching_strategy</EM> - </TD> - <TD>Select the dispatching strategy used by the real-time - event service. A <EM>reactive</EM> strategy will use the - same thread that received the event from the supplier to - push the event to all the consumers, - the <EM>priority</EM> strategy will use a prioritized pool - of threads and will query the scheduling service to select - the thread that will dispatch each event; - the <EM>mt</EM> strategy will also use a pool of threads, - but the thread to dispatch is randomly selected. - </TD> - </TR> - - <!-- <TR NAME="ECDispatchingThreads"> --> - <TR> - <TD><CODE>-ECDispatchingThreads</CODE> - <EM>number_of_threads</EM> - </TD> - <TD>Select the number of threads used bythe <EM>mt</EM> - dispatching strategy. - </TD> - </TR> - - <!-- <TR NAME="ECFiltering"> --> - <TR> - <TD><CODE>-ECFiltering</CODE> - <EM>consumer_filtering_strategy</EM> - </TD> - <TD>Select the filtering strategy used by the consumers. - The <EM>null</EM> filtering strategy will build trivial - filters for all consumers. - The <EM>basic</EM> filtering strategy supports - disjunction, conjunctions and timeouts based on the - subscriptions passed by the consumer during the connect - call. - The <EM>priority</EM> filtering strategy supports the same - features, but it also collaborates with the scheduling - service to build the dependency graph. - </TD> - </TR> - - <!-- <TR NAME="ECSupplierFiltering"> --> - <TR> - <TD><CODE>-ECSupplierFiltering</CODE> - <EM>supplier_filtering_strategy</EM> - </TD> - <TD>The event channel can also perform some filtering close - to the suppliers by minimizing the number of consumers - that are tested for given event. - If the strategy is <EM>null</EM> then a global collection - of consumers is maintained and each event is filtered by - each consumer. - If the strategy is <EM>per-supplier</EM> then the EC uses - the supplier publications and the consumer subscriptions - to determine which consumers could potentially be - interested in events for each supplier. - This set of consumers is usually smaller than the complete - set and it is thus faster to traverse it, but keeping more - collections of consumers increases the connection and - disconnection time as well as the memory requirements. - </TD> - </TR> - - <!-- <TR NAME="ECTimeout"> --> - <TR> - <TD><CODE>-ECTimeout</CODE> - <EM>timeout_strategy</EM> - </TD> - <TD>A consumer can request that the event channel generate - periodic or oneshot timeout events. - This option controls the strategy to generate the - timeouts, - using <EM>reactive</EM> the same reactor used for the ORB - is used by the event service. - The <EM>priority</EM> strategy uses a prioritized group of - threads, timeouts with higher rate are generated by - threads of higher priority. - <BR><B>NOTE: The <EM>priority</EM> strategy is not - implemented</B> - </TD> - </TR> - - <!-- <TR NAME="ECObserver"> --> - <TR> - <TD><CODE>-ECObserver</CODE> - <EM>observer</EM> - </TD> - <TD>The event channel uses the Observer pattern to report - changes in the subscriptions and publications of its - suppliers and consumers; this is specially useful in the - implementation of event channel gateways. - The user can disable this feature by selecting the - <EM>null</EM> strategy; - whereas the <EM>basic</EM> strategy provides a simple, yet - efficient implementation. - </TD> - </TR> - - <!-- <TR NAME="ECScheduling"> --> - <TR> - <TD><CODE>-ECScheduling</CODE> - <EM>scheduling_strategy</EM> - </TD> - <TD>The event channel can collaborate with the scheduling - service to build the dependency list between the consumers - and the suppliers. - If the <EM>null</EM> scheduling strategy is selected this - feature is disabled, - the <EM>priority</EM> strategy enables this feature. - <BR><B>NOTE:<B> The default is to have the feature disabled. - </TD> - </TR> - - <!-- <TR NAME="ECPushSupplierSet"> --> - <TR> - <TD><CODE>-ECPushSupplierSet</CODE> - <EM>strategy</EM> - </TD> - <TD><P>Consumers can connect and disconnect from the event - channel as part of push to one consumer; - changing the set of consumers as a result of such an - operation would invalidate the iterators used by the event - channel to dispatch to the relevant consumers. - There are several ways to handle this problem, for example - a copy of the set could be made <I>before</I> initiating - the dispatch, or only if there is a change on the set - <I>during</I> the dispatch. - If the dispatching strategy is not reactive then it is - possible to lock the set of consumers during the duration - of the dispatch operation, the change in the subscriptions - will be held until the event is completely processed. - Finally the subscription change could be delayed until the - event is fully processed and there is no risk of - invalidating an iterator. - </P> - <P>All this strategies have merits under different - circumstances, the user can select the right one for his - application using this option. - The <EM>immediate</EM> strategy will perform any changes - on the consumer set immediately, simply using a lock to - synchronize access. The <EM>delayed</EM> operation will - wait until there are no threads iterating over the set - to perform any modifications on it. - The <EM>immediate_st</EM> simply performs the - modications without taking any locks, it is useful for - single threaded applications that do not receive changes - are part of an upcall (for example: if there are no - collocated consumers). - </P> - </TD> - </TR> - - <!-- <TR NAME="ECProxyConsumerLock"> --> - <TR> - <TD><CODE>-ECProxyConsumerLock</CODE> - <EM>lock_type</EM> - </TD> - <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or - <EM>recursive</EM>) to synchronize access to the - ProxyPushConsumer state. - </TD> - </TR> - - <!-- <TR NAME="ECProxySupplierLock"> --> - <TR> - <TD><CODE>-ECProxySupplierLock</CODE> - <EM>lock_type</EM> - </TD> - <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or - <EM>recursive</EM>) to synchronize access to the - ProxyPushSupplier state. - </TD> - </TR> - - <!-- <TR NAME="ECConsumerAdminLock"> --> - <TR> - <TD><CODE>-ECConsumerAdminLock</CODE> - <EM>lock_type</EM> - </TD> - <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or - <EM>recursive</EM>) to synchronize access to the - ConsumerAdmin state. - </TD> - </TR> - - <!-- <TR NAME="ECSupplierAdminLock"> --> - <TR> - <TD><CODE>-ECSupplierAdminLock</CODE> - <EM>lock_type</EM> - </TD> - <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or - <EM>recursive</EM>) to synchronize access to the - SupplierAdmin state. - </TD> - </TR> - </TABLE> - </P> - - <H3>The constructor</H3> - - <P>The <CODE>TAO_EC_Event_Channel</CODE> class implements the - <CODE>RtecEventChannelAdmin::EventChannel</CODE> interface; - this class takes one mandatory and two optional parameters in - its constructor: - </P> - -<PRE> - TAO_EC_Event_Channel (const TAO_EC_Event_Channel_Attributes& attributes, - TAO_EC_Factory* factory = 0, - int own_factory = 0); -</PRE> - - <P>The <CODE>factory</CODE> is an optional parameter to override - the default strategy factory used by the event channel, - the event channel will destroy the factory if the - <CODE>own_factory</CODE> argument is true. - </P> - - <P>The <CODE>attributes</CODE> parameter can be used to fine tune - some of the algorithms and strategies used by the event channel, - the default values are probably OK for most applications. - Notice that the attributes include the POA used to activate the - ConsumerAdmin, SupplierAdmin, ProxyPushConsumer and - ProxyPushSupplier objects; - this POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the - <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does). - </P> - - <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> - <TR><TH>Attribute</TH><TH>Description</TH></TR> - - <TR><TD><CODE>consumer_reconnecto</CODE></TD> - <TD>If the attribute is not zero then the same consumer can - call <CODE>connect_push_consumer</CODE> on its - ProxyPushSupplier multiple times to change its - subscriptions; - this is usually more efficient that disconnecting and - connecting again. - </TD> - </TR> - - <TR><TD><CODE>supplier_reconnecto</CODE></TD> - <TD>If the attribute is not zero then the same supplier can - call <CODE>connect_push_supplier</CODE> on its - ProxyPushConsumer multiple times to change its - publications; - this is usually more efficient that disconnecting and - connecting again. - </TD> - </TR> - - <TR><TD><CODE>busy_hwm</CODE></TD> - <TD>When using the delayed strategy to update - ProxyPushSupplier sets this flag controls the maximum - number of thread that can simultaneously iterate over the - set before blocking. - It can be used to avoid starvation in delayed updates on - the set. - </TD> - </TR> - - <TR><TD><CODE>max_write_delay</CODE></TD> - <TD>When using the delayed strategy to update - ProxyPushSupplier sets this flag controls the maximum - number of threads that will initiate dispatching - <B>after</B> a change has been posted. - Any thread after that is blocked until the operations are - performed. - It can be used to completely stop starvation of delayed - updates on the set. - </TD> - </TR> - - <TR><TD><CODE>scheduler</CODE></TD> - <TD>Most configurations of the real-time event channel do - not require an scheduler. - If any of the strategies that require an scheduling - service is selected then this attribute should be set - appropiately. - </TD> - </TR> - </TABLE> - </P> - - <P><HR><P> - - Back to the TAO <A HREF="index.html">components documentation</A>. - - <!--#include virtual="/~schmidt/cgi-sig.html" --> - - <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> -<!-- Created: Thu Jul 1 21:44:28 CDT 1999 --> -<!-- hhmts start --> -Last modified: Fri Jul 2 11:24:48 CDT 1999 -<!-- hhmts end --> - </body> -</html> diff --git a/TAO/docs/events_tutorial.html b/TAO/docs/events_tutorial.html deleted file mode 100644 index c07ae139d88..00000000000 --- a/TAO/docs/events_tutorial.html +++ /dev/null @@ -1,1819 +0,0 @@ -<html> -<head> -<title>Using the Real-Time Event Service</title> -</head> - -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<br> -<br> - -<center> -<h1>Using the Real-Time Event Service</h1><P> - -<A HREF="http://www.cs.wustl.edu/~cdgill/">Chris Gill</a>, -<A HREF="http://www.cs.wustl.edu/~harrison/">Tim Harrison</a>, and -<A HREF="http://www.cs.wustl.edu/~coryan/">Carlos O'Ryan</a><br><br> - -<A HREF="mailto:cdgill@cs.wustl.edu">cdgill@cs.wustl.edu</a>, -<A HREF="mailto:harrison@cs.wustl.edu">harrison@cs.wustl.edu</a>, and -<A HREF="mailto:coryan@cs.wustl.edu">coryan@cs.wustl.edu</a><br> -</center> - -<br> -<br> - -<P><HR><P> -<!-- ************************************************************ --> - -<center> -<table cellpadding=10 border=0 cellspacing=4> -<tr><td> -<h2><a name="Section0">Overview</a></h2> -<BR> -<BR> -<tr><td> -<h3>Contents</h3> -<BR> -<ol> - <li> <a href="events_tutorial.html#Section0">Overview</a> - <li> <a href="events_tutorial.html#Section1">The COS Event Model</a> - <li> <a href="events_tutorial.html#Section2">Real-Time Event Service Enhancements</a> - <li> <a href="events_tutorial.html#Section3">The Real-Time Event Service</a> - <li> <a href="events_tutorial.html#Section4">Developing Consumers</a> - <li> <a href="events_tutorial.html#Section5">Developing Suppliers</a> - <li> <a href="events_tutorial.html#Section6">Caring For Your Event Channel</a> - <li> <a href="events_tutorial.html#Section7">Sample Applications</a> - <li> <a href="events_tutorial.html#Section8">Reference Materials</a> -</ol> - -<P><HR><P> -<tr><td> -<h3>Introduction</h3> -<BR> -This material is intended to provide an introduction to the COS Event Model, -the Real-Time extensions to that model in TAO, and a set of examples that -illustrate the techniques used to build systems using these models. The CORBA -Event Service provides a flexible model for asynchronous communication among -objects. However, the standard CORBAEvent Service specification lacks -important features required by real-time applications. These features include -event filtering, event correlation, and periodic event processing.<P> - -The standard CORBA operation invocation model supports twoway, oneway, -and deferred synchronous interactions between clients and servers. -The primary strength of the twoway model is its intuitive mapping onto -the <code>object->operation()</code> paradigm supported by OO languages. -In principle, twoway invocations simplify the development of -distributed applications by supporting an implicit request/response -protocol that makes remote operation invocations transparent to the -client. <P> - -In practice, however, the standard CORBA operation invocation models -are too restrictive for real-time applications. In particular, these -models lack asynchronous message delivery, do not support timed -invocations or group communication, and can lead to excessive polling -by clients. Moreover, standard oneway invocations might not implement -reliable delivery and deferred synchronous invocations require the use -of the CORBA Dynamic Invocation Interface (DII), which yields -<A HREF="http://www.cs.wustl.edu/~schmidt/GLOBECOM-96.ps.gz">excessive -overhead</A> for most real-time applications. <P> - -The Event Service is a CORBA Object Service (COS) that is designed to -alleviate some of the restrictions with standard CORBA invocation -models. In particular, the COS Event Service supports asynchronous -message delivery and allows one or more suppliers to send messages to -one or more consumers. Event data can be delivered from suppliers to -consumers without requiring these participants to know about each -other explicitly. <P> - -There are two models (<EM>i.e.</EM>, <EM>push</EM> vs. <EM>pull</EM>) -of participant collaborations in the COS Event Service architecture. -This material focuses on real-time enhancements to the push model, which -allows suppliers of events to initiate the transfer of event data to -consumers. Suppliers push events to the Event Channel, which in turn -pushes the events to consumers. <P> - -Suppliers use Event Channels to push data to consumers. Likewise, -consumers can explicitly pull data from suppliers. The push and pull -semantics of event propagation help to free consumers and suppliers -from the overly restrictive synchronous semantics of the standard -CORBA twoway communication model. In addition, Event Channels can -implement group communication by serving as a replicator, broadcaster, -or multicaster that forward events from one or more suppliers to -multiple consumers.<p> - -</table> -</center> - -<hr><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td align=center> -<center><h2><a name="Section1">The COS Event Model</a></h2></center> -</table></center> - -<table cellpadding=1 border=0 cellspacing=4> -<h3>Relationships Between Modules</h3> - -The role of each component in the COS Event Model is outlined -below:<P> - -<ul> - <li> <b><i>EventChannel</i></b> -- The EventChannel interface provides - two factory methods, which allow applications to obtain consumer and - supplier administration objects, respectively, and use them to create - the other objects described below, to connect to the event channel. <P> - - <li> <b><i>SupplierAdmin</i></b> -- The SupplierAdmin interface provides - factory methods which create the appropriate supplier proxy objects. <P> - - <li> <b><i>ConsumerAdmin</i></b> -- The ConsumerAdmin interface provides - factory methods which create the appropriate consumer proxy objects. <P> - - <li> <b><i>ProxyPullSupplier</i></b> -- The ProxyPullSupplier - interface is used by consumers in the pull model to connect and - disconnect from the channel. This interface inherits from the - PullSupplier interface, and acts as a proxy for the suppliers - from which the channel will pull events. <P> - - <li> <b><i>ProxyPushSupplier</i></b> -- The ProxyPushSupplier - interface is used by consumers in the push model to connect and - disconnect from the channel. This interface inherits from the - PushSupplier interface, and acts as a proxy for the suppliers - which will push events to the channel. <P> - - <li> <b><i>ProxyPullConsumer</i></b> -- The ProxyPullConsumer - interface is used by suppliers in the pull model to connect and - disconnect from the channel. This interface inherits from the - PullConsumer interface, and acts as a proxy for the consumers - on whose behalf the channel will pull events. <P> - - <li> <b><i>ProxyPushConsumer</i></b> -- The ProxyPushConsumer - interface is used by suppliers in the push model to connect and - disconnect from the channel. This interface inherits from the - PushConsumer interface, and acts as a proxy for the consumers - to which the channel will push events. <P> - - <li> <b><i>PullSupplier</i></b> -- The PullSupplier interface provides - the necessary methods of a supplier of events in the pull model. <P> - - <li> <b><i>PushSupplier</i></b> -- The PushSupplier interface provides - the necessary methods of a supplier of events in the push model. <P> - - <li> <b><i>PullConsumer</i></b> -- The PullConsumer interface provides - the necessary methods of a consumer of events in the pull model. <P> - - <li> <b><i>PushConsumer</i></b> -- The PushConsumer interface provides - the necessary methods of a consumer of events in the push model. <P> -</ul> - -<tr><td> -</table> -<br> -<br> -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td align=center> -<center><IMG SRC="http://www.cs.wustl.edu/~schmidt/gifs/ec_participants2.gif"></center> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3>The Push Model</h3> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~schmidt/gifs/ec_push.gif"></center> - -<tr><td> -<UL> - <LI> Consumers - Ultimate targets of events - <LI> Suppliers - Generate events - <LI> Event Channel - Decouple consumers and suppliers by propagating - events to consumers on behalf of suppliers -</UL> -</table></center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> - -<h2><a name="Section2">Real-Time Event Service Enhancements</a></h2> - -<tr><td> -<ul> - <li> <b><i>Prioritized dispatching within preemption - classes</i></b> -- The current implementation can dispatch - events in the same queue by their order of importance, which is - necessary to support priorities within a rate group. <p> - - <li> <b><i>Suspend/resume</i></b> -- If a consumer's event - dependencies change at run-time, it can utilize the - suspend/resume functionality through the new - <code>ProxyPushSupplier::suspend</code> and - <code>ProxyPushSupplier::resume</code> methods. When a - consumer invokes <code>ProxyPushSupplier::suspend</code>, the - dependencies registered with that proxy will be disabled until - the <code>resume</code> methods is called. These enhancements - allow run-time flexibility of event dependencies, but maintains - the determinism required by the system scheduling policy (i.e., - consumers can not add and remove dependencies at run-time - - just suspend and resume them).<p> - - <LI> <B><I>Event data model</I></B> -- The data model may use - unions, untyped buffers, or type anys.<P> - -<LI> <B><I>Event filtering</I></B> -- Consumers may register for -events based on event type, or supplier id. The event channel filters events -based on these registrations, to ensure efficient event delivery.<P> - -<LI> <B><I>Event correlation</I></B> -- Consumers may register -for event delivery based on conjunctive or disjunctive sets of events. Conjunctive -registrations cause the event channel to notify the consumer when <I>all</I> -events in the set have arrived. Disjunctive registrations cause the event channel -to notify the consumer when <I>any</I> event in the set has arrived.<P> - -<LI> <B><I>Periodic event processing</I></B> -- Consumers -may register for suppliers based on timed events. Periodic suppliers push events -into the channel at well defined intervals.<P> - - <LI> <B><I>Active consumers and suppliers</I></B> -- See - <a href="events_tutorial.html#Section3">The Real-Time Event Service</a><P>. - -</ul> -</table> -</center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td align=center> -<h2><a name="Section3">The Real-Time Event Service</a></h2> -</table></center> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3>Real-Time ORB and Services</h3> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~schmidt/gifs/corbaopt10.gif"></center> - -<br> -<center><tr><td> -<ul> - <li> Real-time event dispatching<P> - <UL> - <LI> Priority-based queueing and preemption mechanisms<P> - </UL> - <li> Centralized event filtering and correlation<P> - <ul> - <LI> Source/type-based filtering<P> - <LI> Conjunction/Disjunction (AND/OR) correlations<P> - </ul> - - <li> Periodic and Aperiodic processing <P> - <UL> - <LI> Canonical timeouts<P> - <LI> Dependency timeouts - </UL> -</ul> -</center> -</table></center> -<br> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td align=center> -<h3>Real-Time Event Service Internals</h3> -<BR> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~schmidt/gifs/ec_dispatching.gif"></center> -</table></center> -<br> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3>Characteristics of Real-Time Push Event Service Participants</h3> - -<tr><td> -Two major roles are played by the participants in a real-time push event -service.<P> - -<tr><td> -The first role is that of an event consumer, which receives events from the -event channel. A consumer specifies the type and/or source id for each event -it is interested in receiving.<P> - -In hard real-time applications, a consumer must also specify RT_Info data for -each event it is interested in receiving, and any other events on which that -event depends. The RT_Info structure resides in the Scheduler, and is -accessed through the scheduler interface. A unique handle is returned to the -consumer when an RT_Info is created, which can then be used to set the -information in the RT_Info. An RT_Info handle may also be obtained via the -Scheduler's lookup method.<P> - -<tr><td> -The second role is that of an event supplier, which generates events and -passes them into the event channel. A supplier must specify its source id, -and the type of each event it will generate. - -<tr><td> -In hard real-time applications, a supplier must also specify RT_Info data for -the events it will generate. In particular, it must specify the maximum rate -at which it will generate each event. This information is used by a real-time -scheduler to assign appropriate dispatch priorities.<P> - -<tr><td> -Note that the event channel may also be configured to use a null scheduling service. This will -cause all operations to be dispatched at the same priority, and will not require the application -to specify worst case execution times, periods, etc. - -<tr><td> -The consumer and supplier roles may be combined, as illustrated in the tables below. There are -two main cases in which the roles are combined: a passive one termed Consumer/Supplier which -borrows a thread of execution to produce events, and an active one termed Supplier/Consumer -which produces events in its own thread. Both consume events and produce events.<P> -</table></center> - -<br> -<br> -<center><table cellpadding=4 border=1 cellspacing=4> -<h4>EC Roles and Specified RT_Info Contents</h4> - -<tr> -<th>EC Roles -<th>RT_Info Contents -<th>Domain Examples -</tr> - -<tr> -<td> Consumer -<td> dependencies (and optionally, importance) -<td> Display, Exception & Maintenance Logs -</tr> - -<tr> -<td> Consumer/Supplier -<td> dependencies (and optionally, importance) -<td> Navigation Component (NAV) -</tr> - -<tr> -<td> Supplier/Consumer -<td> rate, dependencies (and optionally, importance) -<td> Kalman Filter -</tr> - -<tr> -<td> Supplier -<td> rate -<td> Operator Control Panel, EC Reactor Threads -</tr> - -</table></center> -<BR> -<BR> - - -<center><table cellpadding=1 border=1 cellspacing=4> -<h4>EC Roles and Scheduler Dependency Chain</h4> - -<tr> -<th> EC Roles -<th> Scheduler Dependency Chain -</tr> - -<tr> -<td> Pure Consumer -<td> root node -</tr> - -<tr> -<td> Consumer/Supplier -<td> internal node -</tr> - -<tr> -<td> Supplier/Consumer -<td> internal node -</tr> - -<tr> -<td> Pure Supplier -<td> leaf node -</tr> - -</table></center> -<BR> -<BR> - -<center><table cellpadding=1 border=1 cellspacing=4> -<h4>EC Roles, Threading, and CORBA Roles</h4> - -<tr> -<th> EC Roles -<th> Activity -<th> Thread Behavior -<th> CORBA Roles -</tr> - -<tr> -<td> Pure Consumer -<td> Passive -<td> Threads optional, "internal", wait for an event to occur -<td> Servant -</tr> - -<tr> -<td> Consumer/Supplier -<td> Passive -<td> Threads optional, "internal", wait for an event to occur -<td> Client and/or Servant -</tr> - -<tr> -<td> Supplier/Consumer -<td> Active -<td> Threads required and visible to EC: consume events and actively produce other events -<td> Client and/or Servant -</tr> - -<tr> -<td> Pure Supplier -<td> Active -<td> Threads required and visible to EC: actively produce events -<td> Client -</tr> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~cdgill/ec_roles.GIF"></center> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~cdgill/ec_roles2.GIF"></center> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~cdgill/ec_backbone.GIF"></center> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~cdgill/distributed_ec_roles.GIF"></center> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><IMG SRC="http://www.cs.wustl.edu/~cdgill/ec_orb_view.GIF"></center> -</table></center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<center><h2><a name="Section4">Developing Consumers</a></h2></center> -<br> -<ul> - <li> <a href="events_tutorial.html#Section4_1">Providing QoS Information</a> - <li> <a href="events_tutorial.html#Section4_2">Connecting Consumers to the Event Channel</a> - <li> <a href="events_tutorial.html#Section4_3">Receiving Events</a> - <li> <a href="events_tutorial.html#Section4_4">Disconnecting Consumers from the Event Channel</a> -</ul> -</table></center> - -<P><hr width="75%"><P> <!-- intra-section separator --> -<center><table cellpadding=1 border=0 cellspacing=4> -<center><h3><a name="Section4_1">Providing QoS Information</a><h3></center><p> - -<tr><td> -The following steps are only necessary for applications that make use of the -Event Service's hard real-time features. Applications that do not need these -features and are configured with a null scheduler may skip the following -operations on the scheduling server. - -<tr><td> -For each operation, a Consumer should provide the worst case, expected, and -cached execution time for that operation. It must also specify criticality and -importance values for each operation. A real-time scheduler uses this information -to order dispatches within a set of operations whose dependencies have been met. - -<tr><td> -If it is a Consumer/Supplier (one which consumes an event and passively generates -one or more events from the thread in which it was called, as illustrated in the -tables above), it must provide dependencies on one or more other events to the -scheduler. - -<tr><td> -If it is a Supplier/Consumer (one which consumes an event and actively generates -one or more events from its own thread, as illustrated in the tables above), it -must also specify the rate at which it will generate the new events by passing a -positive value in the period argument to the scheduler set method. It may also -indicate a positive number of threads in which the dispatch will be made. If the -number of threads given is zero, but a period is specified, the number of threads -defaults to 1. - -</table> -</center> - - -<center><table cellpadding=1 border=0 cellspacing=4> - -<tr><td> -<pre> - - // Obtain a reference to the scheduler server. - RtecScheduler::Scheduler_ptr server = - ACE_Scheduler_Factory::server (); - - // Create new RT_Info descriptors for three events. - - RtecScheduler::handle_t handle1 = - server->create ("event_1", // Name of entry point - TAO_TRY_ENV // Environment - ); - - RtecScheduler::handle_t handle2 = - server->create ("event_2", // Name of entry point - TAO_TRY_ENV // Environment - ); - - RtecScheduler::handle_t handle3 = - server->create ("event_3", // Name of entry point - TAO_TRY_ENV // Environment - ); - - - // Register as a consumer/supplier: act as a supplier of event_1 but with - // a consumer dependency on event_3. Therefore, the actual period and - // number of threads for event_1 depends on the characteristics of event_3. - server->set (handle1, // RT_Info handle - RtecScheduler::HIGH_CRITICALITY, // Criticality - 500, // Worst case time (in 100 nanosecs) - 500, // Typical time (in 100 nanosecs) - 500, // Cached time (in 100 nanosecs) - 0, // Period - will depend on event_3 - RtecScheduler::LOW_IMPORTANCE, // Importance - 0, // Quantum (unused) - 0, // Threads - will depend on event_3 - RtecScheduler::OPERATION, // Info type - TAO_TRY_ENV); - - // Register as a producer of event_2. - server->set (handle2, // RT_Info handle - RtecScheduler::HIGH_CRITICALITY, // Criticality - 500, // Worst case time (in 100 nanosecs) - 500, // Typical time (in 100 nanosecs) - 500, // Cached time (in 100 nanosecs) - 50000 * 10, // Period in 100 nsec (= 20 Hz) - RtecScheduler::LOW_IMPORTANCE, // Importance - 0, // Quantum (unused) - 1, // Threads - RtecScheduler::OPERATION, // Info type - TAO_TRY_ENV); - - // Register as a consumer of event_3. - server->set (handle3, // RT_Info handle - RtecScheduler::HIGH_CRITICALITY, // Criticality - 500, // Worst case time (in 100 nanosecs) - 500, // Typical time (in 100 nanosecs) - 500, // Cached time (in 100 nanosecs) - 0, // Period - will depend on supplier - RtecScheduler::LOW_IMPORTANCE, // Importance - 0, // Quantum (unused) - 0, // Threads - will depend on supplier - RtecScheduler::OPERATION, // Info type - TAO_TRY_ENV); - - - // Establish a dependency of event_1 on event_3. - server->add_dependency (handle1, // handle that depends - handle3, // handle that is depended on - 1, // number of calls per event occurance - TAO_TRY_ENV // environment - ); - - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3> -<a name="Section4_2">Connecting Consumers to the Event Channel</a> -</h3> - -<tr><td> -The following code is derived from the EC_Throughput consumer code, which can be -found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp</a> - -<tr><td> -<pre> - -void -Test_Consumer::connect (const char* name, - int event_a, int event_b, - RtecEventChannelAdmin::EventChannel_ptr ec, - CORBA::Environment& _env) -{ - - // Register operations with the scheduling service. The following steps are - // only necessary for applications that make use of the Event Service's hard - // real-time features. Applications that do not need these features and are - // configured with a null scheduler may skip the following operations on the - // scheduling server. - - // Obtain a reference to the scheduler from the ACE_Scheduler_Factory. - RtecScheduler::Scheduler_ptr server = - ACE_Scheduler_Factory::server (); - - // Create a new RT_Info entry for the function identifier - // we were passed, and hang onto the handle to the RT_Info. - RtecScheduler::handle_t rt_info = - server->create (name, _env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Set the attributes for the RT_Info. - ACE_Time_Value tv (0, 2000); - TimeBase::TimeT time; - ORBSVCS_Time::Time_Value_to_TimeT (time, tv); - server->set (rt_info, - RtecScheduler::VERY_HIGH_CRITICALITY, - time, time, time, - 0, - RtecScheduler::VERY_LOW_IMPORTANCE, - time, - 0, - RtecScheduler::OPERATION, - _env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Specify a disjunctive dependency on the arrival of event_a, the arrival - // of event b, OR the arrival of an event service shutdown event. Note that - // the same RT_Info is used for each event. This can be used to simplify - // code in applications using a null scheduler, or to consolidate events - // with identical characteristics in hard real-time applications. - ACE_ConsumerQOS_Factory qos; - qos.start_disjunction_group (); - qos.insert_type (ACE_ES_EVENT_SHUTDOWN, rt_info); - qos.insert_type (event_a, rt_info); - qos.insert_type (event_b, rt_info); - - // = Connect as a consumer. - - // Obtain a reference to the consumer administration object. - RtecEventChannelAdmin::ConsumerAdmin_var consumer_admin = - ec->for_consumers (_env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Obtain a reference to the push supplier proxy. - this->supplier_proxy_ = - consumer_admin->obtain_push_supplier (_env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Obtain a reference to this object. - RtecEventComm::PushConsumer_var objref = this->_this (_env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Connect as a consumer. - this->supplier_proxy_->connect_push_consumer (objref.in (), - qos.get_ConsumerQOS (), - _env); - TAO_CHECK_ENV_RETURN_VOID(_env); -} - -</pre> - -<tr><td> -The following code is derived from the EC_Throughput consumer driver code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Consumer_Driver.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Consumer_Driver.cpp</a> - -<tr><td> -<pre> - -int -ECT_Consumer_Driver::run (int argc, char* argv[]) -{ - // argc/argv are used to initialize the ORB and the options - // for this particular test. Other applications may hard-code - // the ORB options, obtain them from another source, etc. - - TAO_TRY - { - // The use of TAO_TRY macros isolate us from the differences - // between platforms with and without native C++ exceptions. - // This is work in progress and may change in the future! - - // Below is some boiler plate code to initialize the ORB and - // the POA. Notice that applications that connect to the Event - // Channel play the server role in some instances, because - // they receive push() requests (as Consumers) or - // disconnect_push_supplier() requests (as Suppliers). - - // Initialize the ORB reference. - this->orb_ = - CORBA::ORB_init (argc, argv, "", TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Initialize the root POA reference. - CORBA::Object_var poa_object = - this->orb_->resolve_initial_references("RootPOA"); - if (CORBA::is_nil (poa_object.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to initialize the POA.\n"), - 1); - - // Obtain the narrowed root POA reference. - PortableServer::POA_var root_poa = - PortableServer::POA::_narrow (poa_object.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Obtain a reference to the POA manager. - PortableServer::POAManager_var poa_manager = - root_poa->the_POAManager (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Now some boiler plate code to obtain a reference to the - // naming service..... - - // Resolve a reference to the naming service. - CORBA::Object_var naming_obj = - this->orb_->resolve_initial_references ("NameService"); - if (CORBA::is_nil (naming_obj.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to get the Naming Service.\n"), - 1); - - // Narrow the naming service reference. - CosNaming::NamingContext_var naming_context = - CosNaming::NamingContext::_narrow (naming_obj.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Use the Naming Service to locate the Scheduling Service and - // use the Scheduler_Factory to keep a global pointer to the - // latter. - - // Initialize the scheduler factory to operate in configuration mode. - if (ACE_Scheduler_Factory::use_config (naming_context.in ()) == -1) - return -1; - - // Use the Naming Service to locate the Event Service.... - - // Set up the event service lookup name. - CosNaming::Name name (1); - name.length (1); - name[0].id = CORBA::string_dup ("EventService"); - - // Resolve a reference to the event service. - CORBA::Object_var ec_obj = - naming_context->resolve (name, TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Narrow the reference to the event service. - RtecEventChannelAdmin::EventChannel_var channel; - if (CORBA::is_nil (ec_obj.in ())) - channel = RtecEventChannelAdmin::EventChannel::_nil (); - else - channel = RtecEventChannelAdmin::EventChannel::_narrow (ec_obj.in (), - TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Activate the POA so we can start receiving requests... - - // Activate the POA manager. - poa_manager->activate (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Connect consumers to the event service. - this->connect_consumers (channel.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - ACE_DEBUG ((LM_DEBUG, "connected consumer(s)\n")); - ACE_DEBUG ((LM_DEBUG, "running the test\n")); - - // Run the event loop. - if (this->orb_->run () == -1) - ACE_ERROR_RETURN ((LM_ERROR, "%p\n", "orb->run"), -1); - ACE_DEBUG ((LM_DEBUG, "event loop finished\n")); - - this->dump_results (); - - // Disconnect consumers from the event service. - this->disconnect_consumers (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Destroy the event service. - channel->destroy (TAO_TRY_ENV); - TAO_CHECK_ENV; - } - TAO_CATCH (CORBA::SystemException, sys_ex) - { - TAO_TRY_ENV.print_exception ("SYS_EX"); - } - TAO_CATCHANY - { - TAO_TRY_ENV.print_exception ("NON SYS EX"); - } - TAO_ENDTRY; - return 0; -} - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<!-- Must be after suppliers connect. --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3><a name="Section4_3">Receiving Events</a></h3><p> - -<tr><td> -The following code is derived from the EC_Throughput consumer code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp</a> - -<tr><td> -<pre> - -void -Test_Consumer::push (const RtecEventComm::EventSet& events, - CORBA::Environment &_env) -{ - // Make sure at least one event was pushed. - if (events.length () == 0) - { - // ACE_DEBUG ((LM_DEBUG, "no events\n")); - return; - } - - // Make sure only one thread has access. - ACE_GUARD (ACE_SYNCH_MUTEX, ace_mon, this->lock_); - - // We start the timer as soon as we receive the first event. - if (this->recv_count_ == 0) - this->timer_.start (); - - // Update the count of received events. - this->recv_count_ += events.length (); - - if (TAO_debug_level > 0 - && this->recv_count_ % 1000 == 0) - { - ACE_DEBUG ((LM_DEBUG, - "ECT_Consumer (%P|%t): %d events received\n", - this->recv_count_)); - } - - // Loop through the events, looking for shutdown events. - for (u_int i = 0; i < events.length (); ++i) - { - if (events[i].header.type == ACE_ES_EVENT_SHUTDOWN) - { - this->shutdown_count_++; - if (this->shutdown_count_ >= this->n_suppliers_) - { - // We stop the timer as soon as we realize it is time to - // do so. - this->timer_.stop (); - this->driver_->shutdown_consumer (this->cookie_, _env); - } - } - } -} - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3> -<a name="Section4_4">Disconnecting Consumers from the Event Channel</a> -</h3> - -<tr><td> -The following code is derived from the EC_Throughput consumer code, which can be -found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Consumer.cpp</a> - -<tr><td> -<pre> - -void -Test_Consumer::disconnect (CORBA::Environment &_env) -{ - // Make sure the supplier proxy reference is valid. - if (CORBA::is_nil (this->supplier_proxy_.in ())) - return; - - // Disconnect from further communication with the push - // supplier(s). Each consumer is represented by a unique - // ACE_ES_ConsumerModule instance. Which connection to - // disconnect is determined by the instance for the consumer. - this->supplier_proxy_->disconnect_push_supplier (_env); - TAO_CHECK_ENV_RETURN_VOID(_env); - - // Mark the supplier proxy reference invalid. - this->supplier_proxy_ = - RtecEventChannelAdmin::ProxyPushSupplier::_nil (); - - // We want to stop processing events for this consumer. Above, - // we disconnected the consumer from the Event Channel, so no - // more events will be sent, but we could have some events in - // transit. - - // Without a flushing protocol we need to deactivate the - // servant to stop accepting push () requests for any - // incoming events. - - // Deactivate the servant - PortableServer::POA_var poa = - this->_default_POA (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - PortableServer::ObjectId_var id = - poa->servant_to_id (this, _env); - TAO_CHECK_ENV_RETURN_VOID (_env); - poa->deactivate_object (id.in (), _env); - TAO_CHECK_ENV_RETURN_VOID (_env); -} - -</pre> -</table> -</center> - - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<td> -<h2><a name="Section5">Developing Suppliers</a></h2> - -<ul> - <li> <a href="events_tutorial.html#Section5_1">Providing QoS Information</a> - <li> <a href="events_tutorial.html#Section5_2">Connecting Suppliers to the Event Channel</a> - <li> <a href="events_tutorial.html#Section5_3">Generating Events</a> - <li> <a href="events_tutorial.html#Section5_4">Disconnecting Suppliers from the Event Channel</a> -</ul> -</table> -</center> - - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3><a name="Section5_1">Providing QoS Information</a></h3><p> -<tr><td> -In applications that use hard real-time scheduling, a Supplier should provide -the worst case, expected, and cached execution time for each operation on the -supplier side. Even if these values are small and highly deterministic, it is -generally better to specify them in the supplier's RT_Info rather than folding -them into the RT_Info of each consumer. - -<tr><td> -Such a supplier must also specify criticality and importance values, a period, -and the number of threads for each operation. A real-time scheduler propagates -this information to consumer RT_Infos along the graph of dependencies. The -scheduler then uses the propagated information to order dispatches within a -set of operations whose dependencies have been met. - -<tr><td> -The Event Service matches supplier publications with consumer subscriptions to -provide efficient event filtering. Providing incorrect publications or -subscriptions will result in missed events. The Event Service also uses the -subscription information to create additional dependencies between registered -RT_Infos. Thus, providing correct supplier publication and consumer -subscription information is also critical for correct scheduling in hard -real-time applications. - - -<tr><td> -As noted before in the discussion of consumers, the following steps are only -necessary for applications that make use of the Event Service's hard real-time -features. Applications that do not need these features and are configured -with a null scheduler may skip the following operations on the scheduling -server. - -</table> -</center> - -<center><table cellpadding=1 border=0 cellspacing=4> - -<tr><td> -<pre> - - // Obtain a reference to the scheduler server. - RtecScheduler::Scheduler_ptr server = - ACE_Scheduler_Factory::server (); - - // Create new RT_Info descriptors for two events. - - RtecScheduler::handle_t handle0 = - server->create ("event_0", // Name of entry point - TAO_TRY_ENV // Environment - ); - - RtecScheduler::handle_t handle1 = - server->create ("event_1", // Name of entry point - TAO_TRY_ENV // Environment - ); - - // Register as a producer of event_0. - server->set (handle0, // RT_Info handle - RtecScheduler::HIGH_CRITICALITY, // Criticality - 10, // Worst case time (in 100 nanosecs) - 10, // Typical time (in 100 nanosecs) - 10, // Cached time (in 100 nanosecs) - 50000 * 10, // Period in 100 nanosecs (= 20 Hz) - RtecScheduler::LOW_IMPORTANCE, // Importance - 0, // Quantum (unused) - 1, // Threads - RtecScheduler::OPERATION, // Info type - TAO_TRY_ENV); - - // Register as a producer of event_1. - server->set (handle1, // RT_Info handle - RtecScheduler::HIGH_CRITICALITY, // Criticality - 10, // Worst case time (in 100 nanosecs) - 10, // Typical time (in 100 nanosecs) - 10, // Cached time (in 100 nanosecs) - 50000 * 10, // Period in 100 nanosecs (= 20 Hz) - RtecScheduler::LOW_IMPORTANCE, // Importance - 0, // Quantum (unused) - 1, // Threads - RtecScheduler::OPERATION, // Info type - TAO_TRY_ENV); - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<td> -<h3><a name="Section5_2">Connecting Suppliers to Event Channel</a></h3><P> -<p> - -<tr><td> -The following code is derived from the EC_Throughput supplier code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp</a> - - -<tr><td> -<pre> - -void -Test_Supplier::connect (const char* name, - int burst_count, - int burst_size, - int event_size, - int burst_pause, - int event_a, - int event_b, - RtecEventChannelAdmin::EventChannel_ptr ec, - CORBA::Environment &_env) -{ - // Some application-specific setup code. - - // Store the passed parameters in the object. - this->burst_count_ = burst_count; - this->burst_size_ = burst_size; - this->event_size_ = event_size; - this->burst_pause_ = burst_pause; - this->event_a_ = event_a; - this->event_b_ = event_b; - - // Register operations with the scheduling service. The following steps are - // only necessary for applications that make use of the Event Service's hard - // real-time features. Applications that do not need these features and are - // configured with a null scheduler may skip the following operations on the - // scheduling server. - - // Obtain a reference to the scheduling service. - RtecScheduler::Scheduler_ptr server = - ACE_Scheduler_Factory::server (); - - // Create an RT_Info descriptor for the passed operation name. - RtecScheduler::handle_t rt_info = - server->create (name, _env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Calculate the period at which to supply events. - ACE_Time_Value tv (0, burst_pause); - RtecScheduler::Period_t rate = tv.usec () * 10; - - // Set the information in the RT_Info descriptor. - tv.set (0, 2000); - TimeBase::TimeT time; - ORBSVCS_Time::Time_Value_to_TimeT (time, tv); - server->set (rt_info, - RtecScheduler::VERY_HIGH_CRITICALITY, - time, time, time, - rate, - RtecScheduler::VERY_LOW_IMPORTANCE, - time, - 1, - RtecScheduler::OPERATION, - _env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Now, create a supplier id, and publish the events - // that will be supplied under this id. - - // Create a supplier id from the passed name - this->supplier_id_ = ACE::crc32 (name); - ACE_DEBUG ((LM_DEBUG, "ID for <%s> is %04.4x\n", name, - this->supplier_id_)); - - // Publish the events the supplier provides. - ACE_SupplierQOS_Factory qos; - qos.insert (this->supplier_id_, - event_a, - rt_info, 1); - qos.insert (this->supplier_id_, - event_b, - rt_info, 1); - qos.insert (this->supplier_id_, - ACE_ES_EVENT_SHUTDOWN, - rt_info, 1); - - // And finally, some boiler plate code to connect a supplier - // to the Event Service. This is where the connection is - // actually made. - - // Obtain a reference to the supplier administration object. - RtecEventChannelAdmin::SupplierAdmin_var supplier_admin = - ec->for_suppliers (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Obtain a reference to the consumer proxy object. - this->consumer_proxy_ = - supplier_admin->obtain_push_consumer (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Obtain a reference to this supplier object. - RtecEventComm::PushSupplier_var objref = - this->supplier_._this (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Connect as a supplier of the published events. - this->consumer_proxy_->connect_push_supplier (objref.in (), - qos.get_SupplierQOS (), - _env); - TAO_CHECK_ENV_RETURN_VOID (_env); -} - -</pre> - - -<tr><td> -The following code is derived from the EC_Throughput supplier driver code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Supplier_Driver.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Supplier_Driver.cpp</a> - -<tr><td> -<pre> - -int -ECT_Supplier_Driver::run (int argc, char* argv[]) -{ - // argc/argv are used to initialize the ORB and the options - // for this particular test. Other applications may hard-code - // the ORB options, obtain them from another source, etc. - - TAO_TRY - { - // The use of TAO_TRY macros isolate us from the differences - // between platforms with and without native C++ exceptions. - // This is work in progress and may change in the future! - - // Below is some boiler plate code to initialize the ORB and - // the POA. Notice that applications that connect to the Event - // Channel play the server role in some instances, because - // they receive push() requests (as Consumers) or - // disconnect_push_supplier() requests (as Suppliers). - - // Initialize the ORB reference. - CORBA::ORB_var orb = - CORBA::ORB_init (argc, argv, "", TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Initialize the root POA reference. - CORBA::Object_var poa_object = - orb->resolve_initial_references("RootPOA"); - if (CORBA::is_nil (poa_object.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to initialize the POA.\n"), - 1); - - // Obtain the narrowed root POA reference. - PortableServer::POA_var root_poa = - PortableServer::POA::_narrow (poa_object.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Obtain a reference to the POA manager. - PortableServer::POAManager_var poa_manager = - root_poa->the_POAManager (TAO_TRY_ENV); - TAO_CHECK_ENV; - - - // Now some boiler plate code to obtain a reference to the - // naming service..... - - // Resolve a reference to the naming service. - CORBA::Object_var naming_obj = - orb->resolve_initial_references ("NameService"); - if (CORBA::is_nil (naming_obj.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to get the Naming Service.\n"), - 1); - - // Narrow the naming service reference. - CosNaming::NamingContext_var naming_context = - CosNaming::NamingContext::_narrow (naming_obj.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Use the Naming Service to locate the Scheduling Service and - // use the Scheduler_Factory to keep a global pointer to the - // latter. - - // Initialize the scheduler factory to operate in configuration mode. - if (ACE_Scheduler_Factory::use_config (naming_context.in ()) == -1) - return -1; - - // Use the Naming Service to locate the Event Service.... - - // Set up the event service lookup name. - CosNaming::Name name (1); - name.length (1); - name[0].id = CORBA::string_dup ("EventService"); - - // Resolve a reference to the event service. - CORBA::Object_var ec_obj = - naming_context->resolve (name, TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Narrow the reference to the event service. - RtecEventChannelAdmin::EventChannel_var channel; - if (CORBA::is_nil (ec_obj.in ())) - channel = RtecEventChannelAdmin::EventChannel::_nil (); - else - channel = RtecEventChannelAdmin::EventChannel::_narrow (ec_obj.in (), - TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Activate the POA so we can start receiving requests... - - // Activate the POA manager. - poa_manager->activate (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Connect suppliers to the event service. - this->connect_suppliers (channel.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - ACE_DEBUG ((LM_DEBUG, "connected supplier(s)\n")); - - // Activate the supplier objects - this->activate_suppliers (TAO_TRY_ENV); - TAO_CHECK_ENV; - - ACE_DEBUG ((LM_DEBUG, "suppliers are active\n")); - - // Wait for the supplier threads. - if (ACE_Thread_Manager::instance ()->wait () == -1) - { - ACE_ERROR ((LM_ERROR, "Thread_Manager wait failed\n")); - return 1; - } - - ACE_DEBUG ((LM_DEBUG, "suppliers finished\n")); - - this->dump_results (); - - // Disconnect suppliers from the event service. - this->disconnect_suppliers (TAO_TRY_ENV); - TAO_CHECK_ENV; - } - TAO_CATCH (CORBA::SystemException, sys_ex) - { - TAO_TRY_ENV.print_exception ("SYS_EX"); - } - TAO_CATCHANY - { - TAO_TRY_ENV.print_exception ("NON SYS EX"); - } - TAO_ENDTRY; - return 0; -} - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3><a name="Section5_3">Generating Events</a></h3><P><p> - -<tr><td> -The following code is derived from the EC_Throughput supplier code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp</a> - -<tr><td> -<pre> - -int -Test_Supplier::svc () -{ - TAO_TRY - { - // First, a bunch of code that is specific to this test. - - // Set pause (sleep) value between message bursts. - ACE_Time_Value tv (0, this->burst_pause_); - - // Set up message block for event data. - ACE_Message_Block mb (this->event_size_); - mb.wr_ptr (this->event_size_); - - // Create an event set for one event, initialize event header. - RtecEventComm::EventSet event (1); - event.length (1); - event[0].header.source = this->supplier_id (); - event[0].header.ttl = 1; - - // Set up time stamps in event header. This is for performance - // measurements, so this step can be omitted at will. - ACE_hrtime_t t = ACE_OS::gethrtime (); - ORBSVCS_Time::hrtime_to_TimeT (event[0].header.creation_time, t); - event[0].header.ec_recv_time = ORBSVCS_Time::zero; - event[0].header.ec_send_time = ORBSVCS_Time::zero; - - // Initialize data fields in event. - event[0].data.x = 0; - event[0].data.y = 0; - - // We use replace to minimize the copies. This should result - // in just one memory allocation; - event[0].data.payload.replace (this->event_size_, - &mb); - - // This is where the events are actually pushed into - // the event channel. The test pushes bursts of events, - // pausing a specified interval between bursts. - - // Start the timer, and begin pushing events. - this->timer_.start (); - for (int i = 0; i < this->burst_count_; ++i) - { - // Send a burst of events. - for (int j = 0; j < this->burst_size_; ++j) - { - if (j % 2 == 0) - event[0].header.type = this->event_a_; - else - event[0].header.type = this->event_b_; - - // ACE_DEBUG ((LM_DEBUG, "(%t) supplier push event\n")); - this->consumer_proxy ()->push (event, TAO_TRY_ENV); - - TAO_CHECK_ENV; - } - - // Sleep until it's time to send the next burst. - ACE_OS::sleep (tv); - } - - // Send a "magic" type of event to inform the consumer that we are - // not sending anything else... - - // Send one event shutdown from each supplier - event[0].header.type = ACE_ES_EVENT_SHUTDOWN; - this->consumer_proxy ()->push(event, TAO_TRY_ENV); - TAO_CHECK_ENV; - this->timer_.stop (); - - } - TAO_CATCH (CORBA::SystemException, sys_ex) - { - TAO_TRY_ENV.print_exception ("SYS_EX"); - } - TAO_CATCHANY - { - TAO_TRY_ENV.print_exception ("NON SYS EX"); - } - TAO_ENDTRY; - return 0; -} - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<td> -<h3><a name="Section5_4">Disconnecting Suppliers from the Event Channel</a></h3><P> -<p> - -<tr><td> -The following code is derived from the EC_Throughput supplier code, which -can be found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp"> -$TAO_ROOT/orbsvcs/tests/EC_Throughput/ECT_Supplier.cpp</a> - - -<tr><td> -<pre> - -void -Test_Supplier::disconnect (CORBA::Environment &_env) -{ - // Make sure the consumer proxy reference is valid. - if (CORBA::is_nil (this->consumer_proxy_.in ())) - return; - - // Disconnect communication with the push consumer(s). - this->consumer_proxy_->disconnect_push_consumer (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - - // Mark the consumer proxy reference invalid. - this->consumer_proxy_ = - RtecEventChannelAdmin::ProxyPushConsumer::_nil (); - - // We need to stop accepting disconnect_push_supplier () requests - // for this supplier, before it is safe to destroy the supplier. - // As required by the CORBA spec, you must explicitly deactivate - // a servant before destroying it. - - // Deactivate the servant - PortableServer::POA_var poa = - this->supplier_._default_POA (_env); - TAO_CHECK_ENV_RETURN_VOID (_env); - PortableServer::ObjectId_var id = - poa->servant_to_id (&this->supplier_, _env); - TAO_CHECK_ENV_RETURN_VOID (_env); - poa->deactivate_object (id.in (), _env); - TAO_CHECK_ENV_RETURN_VOID (_env); - RtecEventChannelAdmin::ProxyPushConsumer::_nil (); -} - -</pre> - -</table> -</center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<td> -<h2><a name="Section6">Caring for your Event Channel</a></h2> - - -<BR> - -<ul> - <li> <a href="events_tutorial.html#Section6_1">Creation and Name Service Registration</a> - <li> <a href="events_tutorial.html#Section6_2">Register Suppliers Before Consumers</a> -</ul> -</table> -</center> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3><a name="Section6_1">Creation and Name Service Registration</a><h3><p> - -<tr><td> -The following code is derived from the Event_Service executable, which can be -found in TAO in the file: -<A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/Event_Service/Event_Service.cpp"> -$TAO_ROOT/orbsvcs/Event_Service/Event_Service.cpp</a> - -<tr><td> -<pre> - -int main (int argc, char *argv[]) -{ - TAO_TRY - { - // argc/argv are used to initialize the ORB and the options - // for the Event Service executable. Other applications may - // hard code the ORB options, obtain them from another source, etc. - - // Again the boiler plate code for ORB and POA initialization. - - // Initialize ORB. - CORBA::ORB_var orb = - CORBA::ORB_init (argc, argv, "internet", TAO_TRY_ENV); - TAO_CHECK_ENV; - - if (parse_args (argc, argv) == -1) - return 1; - - CORBA::Object_var poa_object = - orb->resolve_initial_references("RootPOA"); - if (CORBA::is_nil (poa_object.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to initialize the POA.\n"), - 1); - - PortableServer::POA_var root_poa = - PortableServer::POA::_narrow (poa_object.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - PortableServer::POAManager_var poa_manager = - root_poa->the_POAManager (TAO_TRY_ENV); - TAO_CHECK_ENV; - - CORBA::Object_var naming_obj = - orb->resolve_initial_references ("NameService"); - if (CORBA::is_nil (naming_obj.in ())) - ACE_ERROR_RETURN ((LM_ERROR, - " (%P|%t) Unable to initialize the Naming Service.\n"), - 1); - - CosNaming::NamingContext_var naming_context = - CosNaming::NamingContext::_narrow (naming_obj.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Notice the use of auto_ptr<> to automagically manage the - // destruction of the servant. When the auto_ptr goes out - // of scope, its destructor is called, which in turn destroys - // the servant. - - auto_ptr<POA_RtecScheduler::Scheduler> scheduler_impl; - RtecScheduler::Scheduler_var scheduler; - - - // Create a new servant to implement the Scheduling Service, - // register it with the Naming Service, and use the - // Scheduler_Factory to keep a global pointer to the new - // Scheduling Service. - - // This is the name we (potentially) use to register the Scheduling - // Service in the Naming Service. - CosNaming::Name schedule_name (1); - schedule_name.length (1); - schedule_name[0].id = CORBA::string_dup ("ScheduleService"); - - if (global_scheduler == 0) - { - scheduler_impl = - auto_ptr<POA_RtecScheduler::Scheduler>(new ACE_Config_Scheduler); - if (scheduler_impl.get () == 0) - return 1; - scheduler = scheduler_impl->_this (TAO_TRY_ENV); - TAO_CHECK_ENV; - - CORBA::String_var str = - orb->object_to_string (scheduler.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - ACE_DEBUG ((LM_DEBUG, "The (local) scheduler IOR is <%s>\n", - str.in ())); - - // Register the servant with the Naming Context.... - naming_context->bind (schedule_name, scheduler.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - } - - ACE_Scheduler_Factory::use_config (naming_context.in ()); - - // The Event Service can be configured to support priority based - // dispatching (the "default_Module_Factory") or best effort (the - // "Reactive_Module_Factory"). We pick the right module factory - // according to the command line options processed above. - - TAO_Default_Module_Factory default_module_factory; - TAO_Reactive_Module_Factory reactive_module_factory; - - TAO_Module_Factory* module_factory = &default_module_factory; - if (reactive) - module_factory = &reactive_module_factory; - - // Now, create a new event channel servant to implement the - // Event Service, and register it with Naming Service. - - // Construct the event channel using the given module factory. - ACE_EventChannel ec_impl (1, - ACE_DEFAULT_EVENT_CHANNEL_TYPE, - module_factory); - - // Obtain an object reference to the new channel. - RtecEventChannelAdmin::EventChannel_var ec = - ec_impl._this (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Convert the EC object reference to a string. - CORBA::String_var str = - orb->object_to_string (ec.in (), TAO_TRY_ENV); - - // Output the EC object reference string (debug only). - ACE_DEBUG ((LM_DEBUG, - "The EC IOR is <%s>\n", str.in ())); - - // Register the EC with the Naming Service. - CosNaming::Name channel_name (1); - channel_name.length (1); - channel_name[0].id = CORBA::string_dup (service_name); - naming_context->bind (channel_name, ec.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Activate the POA so we can start receiving requests... - - // Activate the POA manager. - poa_manager->activate (TAO_TRY_ENV); - TAO_CHECK_ENV; - - // Run the ORB event loop - ACE_DEBUG ((LM_DEBUG, "%s; running event service\n", __FILE__)); - if (orb->run () == -1) - ACE_ERROR_RETURN ((LM_ERROR, "%p\n", "run"), 1); - - // Now the Event Service is finished. We could deactivate the - // EC and SS here, but we don't need to, as the server is - // going down anyway. - - - // Remove the event service and the scheduling service from - // the Naming Service. - - naming_context->unbind (channel_name, TAO_TRY_ENV); - TAO_CHECK_ENV; - - if (global_scheduler == 0) - { - naming_context->unbind (schedule_name, TAO_TRY_ENV); - TAO_CHECK_ENV; - } - - } - TAO_CATCHANY - { - TAO_TRY_ENV.print_exception ("EC"); - } - TAO_ENDTRY; - - - return 0; -} - -</pre> -</table> -</center> - -<P><hr width="75%"><P> <!-- intra-section separator --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<h3><a name="Section6_2">Register Suppliers before Consumers</a></h3><p> -<BR> -<BR> -<tr><td> -<center> -<IMG SRC="http://www.cs.wustl.edu/~schmidt/gifs/ec_registration.gif"> -</center> -</table></center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<h2><a name="Section7">Sample Applications</a></h2> - -<tr><td> -A number of sample applications are available in the directories under -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/"> -TAO's ORB Services tests</a>. - -<tr><td> -In particular, much of the code shown in this tutorial was drawn from the -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Throughput/"> -EC_Throughput</a> test. This test exercises the Event Service and measures its -throughput capabilities. - -<tr><td> -A similar test, -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/Event_Latency/"> -Event_Latency</a>, measures the latency of events through the Event Service. - -<tr><td> -The -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Basic/"> -EC_Basic</a> test demonstrates the basic use the Event Service. - -<tr><td> -The -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/tests/EC_Multiple/"> -EC_Multiple</a> test shows a number of ways to connect multiple Event Channels. - - -<tr><td> -For the IDL source for the various interfaces, please see -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/orbsvcs/RtecScheduler.idl">RtecScheduler.idl</a>, -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/orbsvcs/CosEventChannelAdmin.idl">CosEventChannelAdmin.idl</a>, -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/orbsvcs/CosEventComm.idl">CosEventComm.idl</a> -and -<a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/orbsvcs/orbsvcs/CosNaming.idl">CosNaming.idl</a>. - - -</table> -</center> - -<P><HR><P> -<!-- ************************************************************ --> - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -<h2><a name="Section8">Reference Materials</a></h2> - -<tr><td> -The following materials were used in developing this tutorial: please refer to them for further information. - -<tr><td> -<br> -<tr><td> -<h3>Books</h3> - -<tr><td> -Mowbray, T. and Zahavi, R. The Essential CORBA, Systems Integration Using Distributed Objects. Wiley, 1995. -ISBN 0-471-10611-9 - -<tr><td> -<br> - -<tr><td> -Baker, S. CORBA Distributed Objects Using Orbix. Addison-Wesley, 1997. ISBN 0-201-92475-7 - -<tr><td> -<br> -<tr><td> -<h3>Papers</h3> - -<tr><td> -<ul> - -<li><a href="http://www.cs.wustl.edu/~schmidt/Arch.ps.gz"> -Architectural Considerations for Deterministic Real-Time ORB -Endsystems and Applications</a> - -<li><a href="http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz"> The -Design and Performance of a Real-Time CORBA Object Event Service</a> - -<li><a href="http://www.cs.wustl.edu/~schmidt/RT-ORB.ps.gz"> The -Design of the TAO Real-Time Object Request Broker</a> - -</ul> - - -<tr><td> - -</table> -</center> - -<P><HR><P> -<!-- ************************************************************ --> - - -<center><table cellpadding=1 border=0 cellspacing=4> -<tr><td> -Last modified 10:50:30 CST 22 December 1998 by Chris Gill -</table></center> - -</body></html> - diff --git a/TAO/docs/exceptions.html b/TAO/docs/exceptions.html deleted file mode 100644 index 8999b2f4aba..00000000000 --- a/TAO/docs/exceptions.html +++ /dev/null @@ -1,22 +0,0 @@ -<!DOCTYPE HTML SYSTEM -"http://www.w3.org/pub/WWW/MarkUp/Cougar/Cougar.dtd"> -<!-- $Id$ --> -<html> <head> -<title>Exception handling</title> -</head> - -<body> -<h1>Exception Handling</h1> - -Since the exception handling macros in TAO can be used with any ORB, -it has been generalized and moved to ACE. - -<h3>Notice that ACE's try macros are now prefered over the original -TAO try macros. You should avoid using them in your applications. -They might be removed completely one day.</h3> - -The new document about exception handling has been moved to -<a href="../../docs/exceptions.html">here</a>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> -</body></HTML> diff --git a/TAO/docs/forwarding.html b/TAO/docs/forwarding.html deleted file mode 100644 index 16b3406a733..00000000000 --- a/TAO/docs/forwarding.html +++ /dev/null @@ -1,111 +0,0 @@ -<html> - <!-- $Id$ --> - <head> - <title>Implementation of location forwarding</title> - </head> - - <BODY text = "#000000" - link="#0000ff" - vlink="#cc0000" - bgcolor="#ffffff"> - - <body> - <HR> - <h1>Location forwarding</h1> - <HR> - <h2>Context</h2> - The motivation to support location forwarding for objects is - to allow objects to move or forward certain requests to other objects. - Moving of objects is very important for the Common Object Services - LifeCycle Service. An objet complying to the LifeCycleObject interface, - defined by the LifeCycle Service should support the move operation. The move - operation allows the client to keep its object reference to the object, - but the object is going to be relocated on the same or a different server. - Making location forwarding transparent to the client is the most important - issue. - - <h2>Communication between server and client</h2> - GIOP defines a message named "LOCATION_FORWARD", which should be used to - inform the client stub, that the object has been moved. The message body - has to contain an object reference to the new location of the forwarded - object. - - - <h2>Server side implementation</h2> - Two approaches are possible, one is that the POA replaces the object with - a forwarding servant, which knows the new location. This servant will then - raise an exception each it time it is called, as supposed to be the - actual object. The exception will be a user exception and will be caught - in the marshalling code of the server request "IIOP_ServerRequest". The involved - methods are "set_exception", "marshall" and "init_reply". "set_exception" will - check the user exceptions for the special one, only raised by the forwarding - servant and will extract the new location. "init_reply" will then create - the proper GIOP Reply message with the message type set to LOCATION_FORWARD. - The message is encoded into a CDR (Common Data Representation) stream. - - The second approach is to use a POA servant locator for the child POA, where - the object resides on. The servant locator will be used each time the object - will be accessed. Basically two methods, named "preinvoke" and "postinvoke" - are called each time before and after the actual upcall to the object. - Forwarding using the servant locator works in the following way. The object - tells its servant locator that it has moved and supports the servant locator - with the new object reference. The object locator then raises a special system - exception "forward_request" in "preinvoke" each time the object is called from now on. - The exception is then caught by the lowest possible level, when the - system exceptions are going to be marshalled. Which is in "TAO_Server_Connection_Handler", - the involved methods are "handle_input" and "send_error". "handle_input" - checks for errors (involving exceptions) and calls "send_error" to create - the proper GIOP Reply containing either the system exception or - the location forwarding in case the system exception was the - "forward_request" exception. - - <h2>Client side implementation</h2> - The client has to expect the location forwarding GIOP message and should - respond to it in setting the IIOP_Profile of its IIOP_Object right. - The IIOP_Object is a low level object, to which CORBA::Object has a - pointer to. The reply type is determined by "TAO_GIOP_Invocation::invoke" - which then calls "TAO_GIOP_Invocation::location_forward". "location_forward" - sets the changes the IIOP_Profile of the object. The call is then - reissued by "TAO_IIOP_Object::do_static_call". - - - <h2>Conclusion</h2> - Changing the IIOP_Profile is transparent to the client. So the - client gets no idea, that the object now resides somewhere else. - - The result of the above mentioned solution is that - if an object moves the client will notice it with the next call to the - object. If the object moves again, the original location is not - bothered at all again. Say if the original location was A, then - it moved to B and finally to C. First location A responeded with - a GIOP Location Forward to the client, then B gets used and finally - after moving the object to C, B will send a GIOP Location - Forward and location C gets used. - - There is "no" concept of a home location. If the object moves - very often and old servers die it might be a problem, because - clients, which did not call on the object lately will not know - where to search. Though in the situation of a home location, there - is also the risk that this server might die and the object - is not reachable any more. - - <h2>Optimization</h2> - In the case, when the object moves several times, a chain - of forwarding servers is created. But this chain might be - easily disturbed by just one server failing. A good idea - is to give the servant locator more intelligence to - tell all the oter/previous servers where the object is now. - This will of course increase the communication overhead - in the case of a move, but we get a high reliability - against dying hosts. - - <HR> - For more details and questions, - <p> - - <address><a href="mailto:mk1@cs.wustl.edu">Michael Kircher</a></address> - <p> - <address><a href="mailto:irfan1@cs.wustl.edu">Irfan Pyarali</a></address> - </body> -</html> - diff --git a/TAO/docs/implrepo.html b/TAO/docs/implrepo.html deleted file mode 100644 index 8263bff6d4c..00000000000 --- a/TAO/docs/implrepo.html +++ /dev/null @@ -1,12 +0,0 @@ -<HTML> -<!-- $Id$ --> -<HEAD> -<TITLE>IR docs have moved</TITLE> -<META HTTP-EQUIV="Refresh" CONTENT="1; URL=implrepo/index.html"> -</HEAD> -<BODY> -<P>The IR docs have moved to <A HREF="implrepo/index.html">here</A>.</P> -<P>This page should automatically redirect you there, if not, click on -the link above.</P> -</BODY> -</HTML>
\ No newline at end of file diff --git a/TAO/docs/implrepo/index.html b/TAO/docs/implrepo/index.html deleted file mode 100644 index 5ce150eeaf7..00000000000 --- a/TAO/docs/implrepo/index.html +++ /dev/null @@ -1,121 +0,0 @@ -<html> - -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> -<meta name="ProgId" content="FrontPage.Editor.Document"> -<title>Implementation Repository</title> -<!-- $Id$ --> -</head> - -<body bgcolor="#FFFFFF" text="#000000"> - -<hr> - -<h2>Implementation Repository in TAO</h2> -<p>The purpose of the Implementation Repository 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. </p> - -<p>In the pages here (and in most of the documentation written for it), -Implementation Repository will often be shortened to ImplRepo or IR.</p> - -<hr> - -<h3>Resources</h3> -<p>The IR in TAO was first based on a paper on the subject by <a href="http://www.triodia.com/staff/michi-henning.html">Michi -Henning</a> called <a href="http://www.triodia.com/staff/michi/cacm.pdf">Binding, -Migration, and Scalability in CORBA</a>. Mr. Henning later went on to -coauthor the book <a href="http://cseng.awl.com/bookdetail.qry?ISBN=0-201-37927-9&ptype=0">Advanced -CORBA Programming in C++</a> and included a chapter on the Implementation -Repository. The description of the IR in this chapter is used as the -specification for TAO's IR. </p> - -<p><a href="usersguide.html">Users Guide</a> - Overall documentation on -how to use the IR in your programs.</p> - -<p><a href="paper.html">The Paper</a> - A paper that has a general -description of the IR. This is also where to look to find information on the -inner working of the IR.</p> - -<p><a href="http://tao.cs.wustl.edu/~brunsch/implrepo.html">Discussion -Page</a> - Notes that I've made while working on the IR.</p> - -<hr> - -<h3>The Future</h3> -<p>A large part of the IR has been implemented, but there are several areas that -are not finished or complete yet.</p> - -<table border="1"> - <tr> - <th><b>Feature</b></th> - <th><b>Status</b></th> - </tr> - <tr> - <td>Persistence</td> - <td>It was removed because of ACE subsetting issues, and a new strategy is - in the works.</td> - </tr> - <tr> - <td>Environment Variables</td> - <td>In the IDL interface, but not used on the server side or implemented in - tao_ir</td> - </tr> - <tr> - <td>Logical Server names</td> - <td>In the IDL interface, but not used on the server side or fully - implemented in tao_ir</td> - </tr> - <tr> - <td>Server Shutdown</td> - <td>Only cooperative shutdown implemented.</td> - </tr> - <tr> - <td>POA/ORB Integration</td> - <td>Only some options have been added, ORBImplRepoIOR, etc.</td> - </tr> - <tr> - <td>Multicast location of IRs</td> - <td>The client part is in the ORB, but the server doesn't listen for it yet.</td> - </tr> - <tr> - <td>Client-side Optimizations</td> - <td>Nothing planned yet</td> - </tr> - <tr> - <td>Server Security</td> - <td>Nothing planned yet</td> - </tr> - <tr> - <td>Federations</td> - <td>Nothing planned yet</td> - </tr> - <tr> - <td>DLL servers</td> - <td>Nothing planned yet</td> - </tr> -</table> - -<hr> - -<h3>Who wrote it?</h3> -<p>The guy currently in charge of the IR is Darrell Brunsch <<a href="mailto:brunsch@cs.wustl.edu">brunsch@cs.wustl.edu</a>>. -You can reach me by either email (which is better), or through the <a href="http://www.cs.wustl.edu/~schmidt/ACE-mail.html">ACE -mailing list</a> <<a href="mailto:ace-useres@cs.wustl.edu">ace-users@cs.wustl.edu</a>>, -or through the <a href="news:comp.soft-sys.ace">comp.soft-sys.ace</a> newsgroup. -The newsgroup mirrors the mailing list, but not the other way. Also, if you use -the mailing list, it is best if you join it before sending a question since -responses are usually just replied back to the group.</p> - -<hr> - -<p>Back to the <a href="../index.html">TAO Documentation</a>.</p> - -</body> - -</html> diff --git a/TAO/docs/implrepo/paper.html b/TAO/docs/implrepo/paper.html deleted file mode 100644 index 22f8e233512..00000000000 --- a/TAO/docs/implrepo/paper.html +++ /dev/null @@ -1,820 +0,0 @@ -<html> - -<head> -<meta http-equiv="Content-Type" -content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> -<title>TAO Implementation Repository</title> -<!-- $Id$ --> -</head> - -<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" -vlink="#CC0000"> - -<hr> - -<h1>TAO Implementation Repository </h1> - -<p>Revision 3.05</p> - -<hr> - -<h2>Table of Contents</h2> - -<ul> - <li><a href="#Changes">Recent Changes</a> </li> - <li><a href="#Overview">Overview</a> <ul> - <li><a href="#PersistentandTransientIORs">Persistent - and Transient IORs</a> </li> - <li><a href="#TheImplementationRepository">The - Implementation Repository</a> </li> - </ul> - </li> - <li><a href="#TAOsImplementationRepository">TAO's - Implementation Repository</a> <ul> - <li><a href="#VirtualServers">Virtual Servers</a> </li> - <li><a href="#PingObject">Ping Object</a></li> - <li><a href="#NewIORs">New IORs</a> <ul> - <li><a href="#WhatwaswrongwiththeoldIOR">What - was wrong with the old IOR?</a> </li> - <li><a href="#WhydoesImplRepocontainanOBJKey">Why - does the Implementation Repository - profile contain an Object Key?</a> </li> - </ul> - </li> - <li><a href="#POAExtensions">POA Extensions</a> </li> - <li><a href="#PossibleFutureGoals">Possible Future - Goals</a> </li> - <li><a href="#ServerRestrictions">Server Restrictions</a> - </li> - <li><a href="#PreliminaryInterface">Preliminary - Interface</a> </li> - </ul> - </li> - <li><a href="#AlternateImplementations">Alternate - Implementations</a> </li> - <li><a href="#AccessingtheImplementationRepository">Accessing - the Implementation Repository</a> <ul> - <li><a href="#HelperApplication">Helper Application</a> - </li> - <li><a href="#LocatinganinstanceofImplRepo">Locating - an instance of the Implementation Repository</a> <ul> - <li><a href="#Serverside">Server Side</a> </li> - <li><a href="#Clientside">Client Side</a> </li> - </ul> - </li> - </ul> - </li> - <li><a href="#Howitworks">How It Works</a> <ul> - <li><a href="#HowServerProducesPersistentIORdefault">How - a server produces a Persistent IOR (in the - default case)</a> </li> - <li><a href="#HowServerProducesPersistentIORcomplex">How - a server produces a Persistent IOR (in the - complex case)</a> </li> - <li><a href="#HowClientUsesPersistentIOR">How a - client uses a Persistent IOR</a> </li> - </ul> - </li> -</ul> - -<hr> - -<h2><a name="Changes">Recent Changes</a></h2> - -<p>Since 3.04</p> - -<ul> - <li>Moved it to the same directory as all the new</li> - <li>After a long delay (too long, if you ask me) addressed - the comments that John Mulhern <<a - href="mailto:9107@mn3.lawson.lawson.com">9107@mn3.lawson.lawson.com</a>> - sent me. </li> -</ul> - -<p>Since 3.03 </p> - -<ul> - <li>Added information on the new POA policy where the format - of the persistent IOR can be changed from that of both - the last-known-server-IOR and Implementation Repository - to that just of the Implementation Repository</li> - <li>TAO is now fork-safe, with the introduction of the - CLOEXEC flag through ACE_CLOEXEC.</li> -</ul> - -<p>Since 3.02 </p> - -<ul> - <li>Added a section to give more detailed information on how - Ping Objects work.</li> - <li>Rewrote the Virtual Server section</li> -</ul> - -<hr> - -<h2><a name="Overview">Overview</a></h2> - -<p>This document describes the proposed design of the TAO -Implementation Repository, which was originally known as the -reactivator/activation service. If you have any questions or -comments on our design, please post them to the <a -href="http://www.cs.wustl.edu/~schmidt/ACE-mail.html">ACE</a> -mailing list <<a href="mailto:ace-useres@cs.wustl.edu">ace-users@cs.wustl.edu</a>> -or send email to Darrell Brunsch <<a -href="mailto:brunsch@cs.wustl.edu">brunsch@cs.wustl.edu</a>>.</p> - -<h3><a name="PersistentandTransientIORs">Persistent and Transient -IORs</a></h3> - -<p>CORBA defines two types of object references: <a -href="http://www.cs.wustl.edu/~schmidt/C++-report-col12.ps.gz">persistent -and transient</a>. The difference between the two stems from the -lifetime of the reference in relation to the lifetime of the -server process that created it. The lifetime of a transient -object reference is limited to the lifetime of its server -process. Once the server process exits the transient object -reference no longer exists. All references to this object should -now be invalid, even if the server is restarted. In contrast, -persistent object references can outlive their originating server -process. Therefore, the server can exit and be restarted without -invalidating its persistent object references. This enables the -implementation of features like automatic server activation and -object migration.</p> - -<p>Note that both persistent and transient object references can -refer to objects that reside in <em>manually activated</em> -servers, <em>i.e.</em>, the so-called ``persistent servers.'' A -persistent server is a server that is launched manually, <em>i.e.</em>, -it is always running. A persistent server can generate transient -references and/or persistent references. </p> - -<p>Developers should be aware that persistence of the object -reference does not imply any persistence on the object -implementation state. It is certainly possible to provide -persistent object references for objects whose state is not -persistent. Therefore, servant implementors are responsible for -preserving the state of their servants, <em>e.g.</em>, using a -database or file. </p> - -<h3><a name="TheImplementationRepository">The Implementation -Repository</a></h3> - -<p>According to the CORBA specification, "The Implementation -Repository contains information that allows the ORB to locate and -activate implementations of objects" [CORBA Spec Rev. 2.2: -2.1.14] In earlier revisions of the specification, there was a -method <code>get_implementation</code> in the CORBA Object -interface. This has been deprecated as of the CORBA 2.2 -specification, leaving both the interface and implementation of -the Implementation Repository to the ORB vendor.</p> - -<p>A good paper describing the functionality of the CORBA -Implementation Repository is "<a -href="http://www.triodia.com/staff/michi/cacm.pdf">Binding, -Migration, and Scalability in CORBA</a>" [Michi Henning]. -This paper describes the following three functions of the -Implementation Repository: </p> - -<ol> - <li>Maintain a registry of known servers.</li> - <li>Record which server is currently running, and which port - and host it uses.</li> - <li>Starts servers on demand if they are registered with the - Implementation Repository.</li> -</ol> - -<p>The TAO Implementation Repository is based on the design in -this paper. He also wrote an earlier <a -href="http://www.triodia.com/staff/michi/binding.txt">email</a> -that may be useful to see the issues involved. The next section -details our goals and plans for the implementation.</p> - -<hr> - -<h2><a name="TAOsImplementationRepository">TAO's Implementation -Repository</a></h2> - -<p>The following is an brief outline of TAO'S Implementation -Repository. </p> - -<ul> - <li>Use of TAO's Implementation Repository will be optional. - Real-time applications can choose not to use the - Implementation Repository according to their - performance/predictability/footprint requirements.</li> - <li>Use of TAO's Implementation Repository will be invisible - to clients and servers for common use-case. For more - complicated behavior, programs can use Implementation - Repository extensions of the POA.</li> - <li>TAO's Implementation Repository will work with any CORBA - client that supports <code>LOCATION_FORWARD</code> IIOP - messages and multiple profiles in IORs, even if the - client is not implemented using TAO.</li> - <li>TAO's Implementation Repository will know if one of the - servers registered with it is running by the use of a - "ping"-like service in the server. This service - allows the Implementation Repository to know when it - should restart the server.</li> - <li>TAO will be fork-safe. Since there will be an open - connection to the client while the server is restarted - (via fork or CreateProcess) then care will be needed to - make sure that the open sockets will be closed in the - client process. The addition of CLOEXEC feature to TAO - will cover this problem.</li> - <li>TAO will exploit features of IIOP 1.1 to safely and - efficiently verify if an IOR was generated by TAO itself - on the client side. The server will still determine this - through the object key, since that is all that is passed - in a request.</li> - <li>TAO will support multiple profiles in IORs. A profile - contains the host/port and object key of a CORBA Object. - An optimization that will be possible is to have a last - known profile of the object as the first profile and an - Implementation Repository as the second profile in an - IOR. The client will first try the object to see if it - still active at the host/port before it contacts the - Implementation Repository. This strategy will reduce - latency. </li> -</ul> - -<h3><a name="VirtualServers">Virtual Servers</a></h3> - -<p>TAO's Implementation Repository must keep track of whether an -object's implementation is currently running or is stopped. To -have a record for every object would require too much overhead, -but having a record for every executable server would be -inflexible and prevent the migration of objects. In the Henning -paper, he mentions the use of a <em>server name</em> as the index -for the table maintained by the Implementation Repository. </p> - -<p>A virtual server does not refer to the executable but instead -to a group of objects. An executable may have one or more virtual -servers within it. This allows one virtual server to be moved off -the executable to another executable (for instance, onto another -machine) without affecting the objects in other virtual servers -on the original executable. </p> - -<p>Each virtual server will be indexed in the Implementation -Repository by a name that is given to it by the user. It is the -users responsibility to make sure that each virtual server name -is unique. By default, this name is the name of the executable -(since by default there is only one virtual server per -executable). However, this default behavior can be overridden. </p> - -<h3><a name="PingObject">Ping Object</a></h3> - -<p>Ping objects are simple objects that reside in the server, one -for every virtual server. It is contacted by the Implementation -Repository to determine if the virtual server is still running -and responding. At certain intervals the Implementation -Repository will invoke a one-way method on the ping object, and -then will expect a "pong" message to be sent back. -Different strategies for pinging (which will depend on a TAO -option) will be used by the implementation repository. If a -server is expected to be responsive, the Implementation -Repository will not wait long for a response before considering -the server to be gone. Other servers may be -computationally-intensive and need to be held under less -stringent expectations.</p> - -<p>We chose the ping method to be a one-way (instead of two-way) -because if the server became unresponsive, it would not return -from the method invocation. The Implementation Repository needs -some form of a timeout with the ping to be able to determine if -the server is unresponsive or not.</p> - -<h3><a name="NewIORs">New IORs</a></h3> - -<p>Standard CORBA IORs contain the following two sections:</p> - -<table border="1"> - <tr> - <td>Type ID</td> - <td>Sequence of Tagged Profiles</td> - </tr> -</table> - -<p>The Type ID is an indicator for the most derived type known at -the time of the reference creation. It is used as a hint for the -client in determining what interfaces the object can support. The -Sequence of Tagged Profiles consist of one or more profiles that -encapsulate information used by the associated protocol in order -to communicate with the object (host, port, object id, etc.).</p> - -<p>Currently, TAO uses only one IIOP 1.0 Tagged Profile, which is -defined as follows:</p> - -<table border="1"> - <tr> - <td>Version</td> - <td>Host</td> - <td>Port</td> - <td>Object Key</td> - </tr> -</table> - -<table border="0"> - <tr> - <td>Object Key: </td> - <td><table border="1"> - <tr> - <td>Transient/Persistent Flag</td> - <td>TimeStamp</td> - <td>POA ID</td> - <td>OBJ ID</td> - </tr> - </table> - </td> - </tr> -</table> - -<p>To accomodate the Implementation Repository and IIOP 1.1, the -Profile was changed according to the CORBA specification as -follows:</p> - -<table border="1"> - <tr> - <td>Version</td> - <td>Host</td> - <td>Port</td> - <td>Object Key</td> - <td>Components</td> - </tr> -</table> - -<table border="0"> - <tr> - <td>Object Key: </td> - <td><table border="1"> - <tr> - <td>TAO</td> - <td>TAO version</td> - <td>TimeStamp/Server Name</td> - <td>POA ID</td> - <td>OBJ ID</td> - </tr> - </table> - </td> - </tr> -</table> - -<p>The two main changes is the addition of the Components field -(which is a IIOP 1.1 thing) and the addition of TAO with its -version. Transient object references will still have a TimeStamp -to ensure uniqueness, but persistent object references will have -a server name to identify themselves to the Implementation -Repository. </p> - -<p>For servers that move around or need to be restarted often, -the IOR will contain a reference to the Implementation Repository -with the object key of the server and the server name imbedded. - Once the client contacts the Implementation Repository, it -will be forwarded to the correct object. This IOR will look like -the following:</p> - -<table border="1"> - <tr> - <td>Version</td> - <td>Host</td> - <td>Port</td> - <td>Object Key</td> - <td>Components</td> - </tr> -</table> - -<table border="0"> - <tr> - <td>Object Key: </td> - <td><table border="1"> - <tr> - <td>TAO</td> - <td>TAO version</td> - <td>Server Name</td> - <td>POA ID</td> - <td>OBJ ID (actually the OBJ Key of the Server)</td> - </tr> - </table> - </td> - </tr> -</table> - -<p>For servers that expect to remain in the same host/port for a -long time, the above IOR can be optimized by placing the server -profile in the IOR before the Implementation Repository -profile. TAO clients will first try the server, and if that -fails, then try the Implementation Repository. Clients from -other ORBs may behave the same way, but this isn't guaranteed -since the handling of multiple profiles is not yet in the CORBA -spec. There will be an option to only generate the IR-only IORs -for ORBs that do not support multiple profiles in the needed -manner. </p> - -<p>There will be a POA policy to determine which type of -Persistent IOR to use. By default, the Implementation -Repository alone version will be used.</p> - -<h4><a name="WhatwaswrongwiththeoldIOR">What was wrong with the -old IOR?</a></h4> - -<p>We need a place to put a TAO marker in the IOR so TAO servers -can differentiate TAO IORs from IORs of other vendors. In the -original scheme used in TAO, Persistent IORs had a null -timestamp. To support virtual servers, we will use that slot to -store the server name so the Implementation Repository knows -which server to launch.</p> - -<h4><a name="WhydoesImplRepocontainanOBJKey">Why does the -Implementation Repository profile contain an Object Key?</a></h4> - -<p>It needs to know what the object key of the object when -forwarding is used. A server may contain more than one object, so -the object key is needed to forward to the correct object on the -server. </p> - -<h3><a name="POAExtensions">POA Extensions</a></h3> - -<p>TAO's POA will contain a new TAO-specific method called <code>create_reference_with_virtual_server[_and_id] -(...)</code>. This method takes additional arguments for a -virtual server name and a sequence of Implementation Repository -IORs. The POA will register the virtual server name with each of -the Implementation Repositories in the sequence passed in. -Several Implementation Repositories can be specified to enhance -availability through redundancy. </p> - -<p>TAO's POA will also contain a policy for the type of IOR -created with <code>create_reference</code>. It can either -produce the standard type, with just a reference to the -Implementation Repository, or it can produce one also containing -a reference to the current server.</p> - -<h3><a name="PossibleFutureGoals">Possible Future Goals</a></h3> - -<p>The following are features that may be added to support TAO's -Implementation Repository: </p> - -<ul> - <li>Optimization on TAO clients to recognize when a server is - restarted, and change all other IORs that contain the - server instead of going through the Implementation - Repository</li> - <li>Some sort of server security that checks the executable - to make sure it is the correct executable (checksum, - signatures, etc).</li> - <li>Add the ability to put servers into DLLs or Shared Object - files so the Implementation Repository can load it via - those methods.</li> - <li>GUI interface for such things as the helper application.</li> - <li>Federations of Implementation Repositories.</li> - <li>The ability to start a remote server (possibly with rsh, - ssh, rexec, etc)</li> -</ul> - -<h3><a name="ServerRestrictions">Server Restrictions</a></h3> - -<p>Most often servers that have Persistent IORs will save their -state to secondary storage. Databases are a good example of this, -where the server can be stopped and restarted with all the -information remaining on disk. </p> - -<p>The server must also make sure it creates the POA and Object -in a way that does not change the POA ID and Object ID. The -Implementation Repository forwards requests based on the -information in the IOR; if the POA ID or Object ID changes, then -the Implementation Repository will be unable to sucessfully -forward requests. If the server implements dynamic servants and -dynamic POA activations, then this is not an issue since the -necessary POAs and servants will be created on demand.</p> - -<h3><a name="PreliminaryInterface">Preliminary Interface</a></h3> - -<p>The following is a proposed IDL interface for the TAO -Implementation Repository: </p> - -<pre>module TAO -{ - // .... - - exception Already_Registered {}; - // Object already bound in the Implementation Repository - - exception Cannot_Activate - { - string reason_; - }; - - exception Not_Found {}; - // Object not found in the Implementation Repository - - struct Environment_Variable - { - string name_; - string value_; - }; - // One environment variable - - struct INET_Addr - { - unsigned short port_; - unsigned long host_; - }; - // The location of a server - - typedef sequence<Environment_Variable> Environment; - // Complete environment - - typedef sequence<string> Command_Line_Options; - // Command line options - - struct Process_Options - { - string executable_name_; - // Executable name - - Command_Line_Options command_line_options_; - // Command line options - - Environment environment_; - // Environment - - string working_directory_; - // Working directory - - unsigned long creation_flags_; - // Creation flags - }; - - interface Ping_Object - { - oneway void ping (); - // Used for checking for liveness of a server. When the server receives - // this, it should send back a response indicating it is sill alive. - // Depending on the policy specified, a timeout can be reached where the - // Implementation Repository will restart the server. - }; - - interface Implementation_Repository - { - Object activate_object (in Object obj) - raises (Not_Found, - Cannot_Activate); - // Restart server that will contain this persistent object and return the - // new Object reference. - // - // The <Not_Found> exception is raised when <obj> is not found - // in the Implementation Repository. The <Cannot_Activate> exception - // is raised when <obj> is found in the Repository but could not be - // activated. - - INET_Addr activate_server (in string server) - raises (Not_Found, - Cannot_Activate); - // Restart server that is named <server> and return the host/port - // - // - // The <Not_Found> exception is raised when <server> is not found - // in the Implementation Repository. The <Cannot_Activate> exception - // is raised when <server> is found in the Repository but could not be - // activated. - - void register_server (in string server, - in Process_Options options) - raises (Already_Registered); - // Restart server process when client is looking for <server>. - // - // The <Already_Registered> exception is raised when <server> has - // already been registered with the Implementation Repository. - // - // The <Object_Not_Persistent> exception is raised when <server> is - // not a Persistent Object Reference. - - void reregister_server (in string server, - in Process_Options options) - raises (Already_Registered); - // Restart server process when client is looking for <server>. - // - // The <Already_Registered> exception is raised when <server> has - // already been registered with the Implementation Repository. - // - // The <Object_Not_Persistent> exception is raised when <server> is - // not a Persistent Object Reference. - - void remove_server (in string server) - raises (Not_Found); - // Remove <server> from the Implementation Repository. - // - // The <Not_Found> exception is raised when <server> is not found - // in the Implementation Repository. - - Profile server_is_running (in string server, - in INET_Addr addr, - in Ping_Object ping); - // Used to notify the Implementation Repository that <server> is alive and - // well at <addr>. - - void server_is_shutting_down (in string server); - // Used to tell the Implementation Repository that <server> is shutting - // down. - }; -};</pre> - -<hr> - -<h2><a name="AlternateImplementations">Alternate Implementations</a></h2> - -<p>Other ORB vendors use alternative techniques for their -Implementation Repositories. These techniques usually require new -naming techniques to access persistent object references and new -client-side APIs to bind to persistent object references. TAO's -Implementation Repository will not require such extensions. </p> - -<p>A possible design alternative for the IR might use an Object -Reference that points to the Implementation Repository instead of -pointing directly to the persistent object. This extra level of -indirection would be used by the Implementation Repository to -start the server, if needed. The Location Forwarding mechanism -would then be used to forward the client request to the server. -The difference between this design and TAO's design is that the -persistent IOR in TAO will contain a profile pointing to a -location of the server (where it still might be running) to try -first, and then only if that fails does the client contact the -Implementation Repository. This is an optimization for case where -the server does not shut down often, and most requests do not -need to be forwarded to a new address.</p> - -<p>In cases where most requests will require a forward, TAO can -support a policy that is just like this alternative, where the -Implmentation Repository will be contacted first.</p> - -<hr> - -<h2><a name="AccessingtheImplementationRepository">Accessing the -Implementation Repository</a> </h2> - -<p>The Implementation Repository will be transparent to the -clients and the servers. Clients will only deal with IIOP 1.1 -IORs, and in the default case all the Implementation Repository -logic on the server side will be handled internally by the ORB -and the POA. </p> - -<h3><a name="HelperApplication">Helper Application</a></h3> - -<p>A helper application will be included with the Implementation -Repository. It will be a command-line utility that will assist -users with adding and removing server records (containing virtual -server names and executable name/options) from the Implementation -Repository. </p> - -<h3><a name="LocatinganinstanceofImplRepo">Locating an Instance -of the Implementation Repository </a></h3> - -<h4><a name="Serverside">Server-side</a></h4> - -<p>In the default case, the Implementation Repository will be -found via the command-line, environment variables, and multicast -(in that order). This location strategy is consistent with that -used by TAO to local its default Naming Service instance. Using -the POA extensions, other Implementation Repositories can be -specified in the call to <code>POA::create_reference_with_virtual_server</code>. -The default port of the Implementation Repository can be -overridden through command-line options or environment variables. -</p> - -<h4><a name="Clientside">Client-side</a></h4> - -<p>One or more Implementation Repositories will be stored in -additional profiles in the IOR. Other Implementation Repositories -can also be located by multicasting (on a default multicast -group) the server name of the Persistent Object the client is -interested in. The default multicast group and default port of -the Implementation Repository can be overridden through command -line options or environment variables. </p> - -<p>In most cases, one Implementation Repository will be enough. -For redundancy, several Implementation Repositories can be -specified.</p> - -<hr> - -<h2><a name="Howitworks">How It Works</a></h2> - -<h3><a name="HowServerProducesPersistentIORdefault">How a server -produces a Persistent IOR (in the default case)</a></h3> - -<p>Before a server starts, it must be registered (via a -command-line utility) with an implementation repository. On -platforms that don't support multicast, the Implementation -Repository must be specified on the command line or in an -environment variable. </p> - -<ol> - <li>When the server starts up it calls <code>ORB_init</code>. - <code>ORB_init</code>, if not passed a server name, will - take argv[0] and use that as a default server name (TAO - expects this to be the executable name). </li> - <li><code>ORB_init</code> will create a ping object.</li> - <li><code>ORB_init</code> will look for Implementation - Repositories on the command-line, environmental - variables, and then through multicast (in that order). - Once it finds one it registers itself and passes the ping - object to the implementation repository with <code>server_is_running</code> - operation. </li> - <li>The profile returned by registration will be stored for - later use.</li> - <li>Client later can call the <code>POA::create_reference</code> - operation.</li> - <li>The <code>create_reference</code> operation will create - the local profile.</li> - <li>The stored Implementation Repository profile will have - its object id changed to be the object key just created.</li> - <li>Both profiles will be joined together if the multiple - profile IOR policy is set, and then returned.</li> -</ol> - -<h3><a name="HowServerProducesPersistentIORcomplex">How a server -produces a Persistent IOR (in complex cases)</a></h3> - -<p>As with the default case, the server must be registered with -an Implementation Repository, although it does not need to be -multicast aware since the IORs will be passed to the POA by the -program. </p> - -<ol> - <li><code>ORB_init</code> is called and does the default work - (if it has Implementation Repositories to contact).</li> - <li><code>POA::create_reference_with_virtual_server[_and_id]</code> - will be called with a server name and list of - Implementation Repositories. </li> - <li>The profile for the object is created.</li> - <li>The ping object created in <code>ORB_init</code> and the - object key is passed to the Implementation Repositories, - and their profiles are returned.</li> - <li>Both profiles will be joined together if the multiple - profile IOR policy is set, and then returned.</li> -</ol> - -<h3><a name="HowClientUsesPersistentIOR">How a client uses a -Persistent IOR</a></h3> - -<p>For all Clients: </p> - -<ul> - <li>Client obtains a Persistent Object Reference, which - contains multiple profiles to both regular objects and - Implementation Repositories.</li> - <li>It will now make a request on the first profile.</li> - <li>If the first profile if the server profile, and the - server is still there, then it will be successful. - If the server has moved (or shut down), then the next - profile will be tried.</li> - <li>If the first profile is the Implementation Repository, or - if the server profile failed, then it will be - contacted. The Implemenation Repository will then - return NOT_FOUND or will start up the server and return a - Location Forward message.</li> -</ul> - -<p>If everything fails, then most clients will return failure for -the request. TAO clients will attempt to contact other -Implementation Repositories that are specified on the -command-line, in environment variables, or found through -multicast. </p> - -<ul> - <li>If all of the profiles fail, then contact the other - Implementation Repositories. First get those specified on - the command line or in environment variables.</li> - <li>Then, if multicast is available: <ul> - <li>Multicast the Object Reference to a group of - Implementation Repositories </li> - <li>Wait until response or a timeout. The response - will contain the Object Reference of a - Implementation Repository that knows about the - Object Reference </li> - </ul> - </li> - <li>Connect to the Implementation Repository that responds - first.</li> - <li>Call <i>activate</i> passing the Persistent Object - Reference.</li> - <li>If a new Object Reference was sent back then retry the - request using the it. If this request fails, then fail - (no more retries).</li> - <li>If a null reference was sent back, then fail.</li> -</ul> - -<p>TAO clients will have an optimization where if there are -several IORs that have the same server name, and one of them gets -forwarded, then the client will be able to change its other IORs -without going through the overhead of contacting Implementation -Repository.</p> - -<hr> - -<p>Last update to this document: $Date$</p> - -<p>Back to <a href="../releasenotes/">TAO Release Notes</a></p> - -<p>Back to <a href="index.html">Implementation Repository</a></p> -</body> -</html> diff --git a/TAO/docs/implrepo/tao_ir.html b/TAO/docs/implrepo/tao_ir.html deleted file mode 100644 index 823957facf1..00000000000 --- a/TAO/docs/implrepo/tao_ir.html +++ /dev/null @@ -1,230 +0,0 @@ -<html> -<!-- $Id$ --> -<head> -<meta http-equiv="Content-Type" -content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> -<title>Implementation Repository User's Guide</title> -</head> - -<body bgcolor="#FFFFFF"> - -<hr> - -<h2>tao_ir Usage</h2> - -<p>The usage of tao_ir is as follows:</p> - -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] <a href="#examples">command</a> -[command-arguments]</code></p> - -<p><i>ORB_options</i> is the ORB options to be given. This is where -options like "-ORBImplRepoIOR" would be placed. <i>command </i>is -one of the supported commands like add, remove, etc. <i>command-arguments</i> -are dependent on the command used. For example, <i>add </i>will need a -server name for registration, but list does not necessarily need any arguments.</p> - -<hr> - -<h3><a name="examples">Examples</a></h3> -<p>There is a file in the current directory name <i>implrepo.ior</i> that -contains the IOR of the Implementation Repository. The server executable -is called <i>airplane.exe</i> and the POA name used by the object is <i>plane</i>. -The server needs the -i option to use the IR and the IOR of the IR. So the -command would be:</p> - -<p><code>tao_ir -ORBImplRepoIOR file://implrepo.ior add plane -c "airplane.exe --i file://implrepo.ior"</code></p> - -<p><code>And if you want to later remove that server from the IR:</code></p> - -<p><code>tao_ir -ORBImplRepoIOR file://implrepo.ior remove plane</code></p> - -<p>Or if you wanted to update the entry to have a working directory of -C:\airplane\.</p> - -<p><code>tao_ir -ORBImplRepoIOR file://implrepo.ior update plane -w -"C:\airplane\"</code></p> - -<hr> - -<h3><a name="commands">Commands</a></h3> - -<p><i>tao_ir</i> currently supports these commands:</p> - -<table border="1"> - <tr> - <th>Command</th> - <th>Description</th> - </tr> - <tr> - <td><a href="#activate">activate</a></td> - <td>Activates a server through the IR</td> - </tr> - <tr> - <td><a href="#add">add</a></td> - <td>Adds a server to the server database in the IR</td> - </tr> - <tr> - <td><a href="#list">list</a></td> - <td>Lists the details of one server or lists all the servers registered in - the IR</td> - </tr> - <tr> - <td><a href="#remove">remove</a></td> - <td>Removes a server from the server database in the IR</td> - </tr> - <tr> - <td><a href="#shutdown">shutdown</a></td> - <td>Shuts down a server through the IR</td> - </tr> - <tr> - <td><a href="#update">update</a></td> - <td>Updates information for a server in the server database in the IR</td> - </tr> -</table> - -<hr> - -<h3><a name="activate">activate</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] activate <i>name </i>[-h]</code></p> - -<p>Activate a server through the Implementation Repository. The <i>name</i> is -the server (POA) name that is used to identify the server.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> -</table> - -<hr> - -<h3><a name="add">add</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] add <i>name </i>[-h] -[-c <i>command</i>] [-w <i>working_dir</i>]</code></p> - -<p>Creates a new server entry in the Implementation Repository. The <i>name</i> -must be be the name of the POA that the object resides in.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> - <tr> - <td>-c <i>command</i></td> - <td>Adds the command line string used to restart this server</td> - </tr> - <tr> - <td>-w <i>working_dir</i></td> - <td>Adds the working directory that is used for the server</td> - </tr> -</table> - -<hr> - -<h3><a name="list">list</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] list [<i>name</i>]<i> -</i>[-h] [-v]</code></p> - -<p>Lists all or one of the server entries in the Implementation Repository. If a -<i>name</i> is used, it will display verbose information about the server -identified by its server (POA) name.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> - <tr> - <td>-v</td> - <td>When listing the list of servers (no <i>name</i> specified), display - verbose information for all servers.</td> - </tr> -</table> - -<hr> - -<h3><a name="remove">remove</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] add <i>name </i>[-h]</code></p> - -<p>Removes a server entry from the Implementation Repository. The <i>name</i> is -the server (POA) name that is used to identify the server.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> -</table> - -<hr> - -<h3><a name="shutdown">shutdown</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] shutdown <i>name </i>[-h]</code></p> - -<p>Shuts down a server through the Implementation Repository. The <i>name</i> is -the server (POA) name that is used to identify the server.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> -</table> - -<hr> - -<h3><a name="update">update</a></h3> -<p><code><b>tao_ir </b>[<a href="../Options.html">ORB options</a>] add <i>name </i>[-h] -[-c <i>command</i>] [-w <i>working_dir</i>]</code></p> - -<p><code>Update a server entry in the Implementation Repository. </code>The <i>name</i> -is the server (POA) name that is used to identify the server.</p> - -<table border="1"> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - <tr> - <td>-h</td> - <td>Displays help for this command</td> - </tr> - <tr> - <td>-c <i>command</i></td> - <td>Changes the command line string used to restart this server</td> - </tr> - <tr> - <td>-w <i>working_dir</i></td> - <td>Changes the working directory that is used for the server</td> - </tr> -</table> - -<hr> - -<p>Back to <a href="index.html">Implementation Repository</a></p> -</body> -</html> diff --git a/TAO/docs/implrepo/usersguide.html b/TAO/docs/implrepo/usersguide.html deleted file mode 100644 index 7c34c93c5d3..00000000000 --- a/TAO/docs/implrepo/usersguide.html +++ /dev/null @@ -1,92 +0,0 @@ -<html> -<!-- $Id$ --> - -<head> -<meta http-equiv="Content-Type" -content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> -<title>Implementation Repository User's Guide</title> -</head> - -<body bgcolor="#FFFFFF"> - -<hr> - -<h3><font color="#FF0000">Warning, this document is out of date and is currently -being updated.</font></h3> - -<h3>Implementation Repository User's Guide</h3> - -<p>Since the POA/ORB integration is not yet completed, the functionality still -exists in separately in IR_Helper, which is included in orbsvcs. When the -integration is done, this dependency to orbsvcs will be removed.</p> - -<hr> - -<h4>What does the server need to do.</h4> - -<p>The IR needs information about the server to be able to direct -to the right place. The current scheme uses a regular persistent -IOR and replaces the host and port with that of the IR. Then when -the call comes into the IR, it sends back a LOCATION_FORWARD to -the client and directs it to the correct server (after starting -it if necessary).</p> - -<p>So the server needs to know the IOR of the IR in order to -change the host and port in it to that of the IR. The information -the IR needs to receive from the server is its POA name (which it -uses as an identifier) and commands used to restart the server.</p> - -<hr> - -<h4>The IR_Helper class</h4> - -<p>Most of the work on the server is done in the IR_Helper class. -The first thing it expects is to have the implrepo.ior file in -the current directory. This file contains the IOR of the IR. -IR_Helper then uses this to register itself. </p> - -<p>Here is the small checklist I went through when I used the -IR_Helper class in Airplane Test. The Cubit-style references are -just refering to any server that has used the structure of the -IDL_Cubit test (a lot of TAO's examples are like this).</p> - -<dir> - <li>Make yourself an IR_Helper object. (If you follow - the Cubit-style architecture, this will be a pointer in - the Server_i class). </li> - <li>After you create the POA, construct the IR_Helper and - pass it the relevant information. (Cubit-style: assign a - new object within Server_i::init) </li> - <li>If you need to register, call register_server () - (Cubit-style: add another option "-r" and have - it set a flag. Within Server_i::init call - register_server ()) </li> - <li>After you create and register your objects, call - change_object to redo the references. Then you can - output the new IOR. (Cubit-style: still within - Server_i::init) </li> - <li>Right before ORB::run call notify_startup and afterwards, - call notify shutdown (Cubit-style: within Server_i::run) </li> -</dir> - -<hr> - -<h4>To use, or not to use the IR</h4> - -<p>If you look at the tests, they use -r and -i flags to -determine how to use the IR. The -i flag turns on the use of the -Implementation Repository (so the server can be tested without -the IR). The -r flag is used to register the entry in the IR for -the server. Note that -r will not work in the example without -i. -This does require some more work on the server side, so if you -choose you can just use the IR all the time and only worry about --r.</p> - -<hr> - -<p>Last update to this document: $Date$</p> - -<p>Back to <a href="index.html">Implementation Repository</a></p> -</body> -</html> diff --git a/TAO/docs/index.html b/TAO/docs/index.html deleted file mode 100644 index 739f2556d16..00000000000 --- a/TAO/docs/index.html +++ /dev/null @@ -1,46 +0,0 @@ -<html> - -<head> - <!-- $Id$ --> -<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0"> -<title>TAO Documentation</title> -</head> - -<body text="#000000" link="#0000ff" vlink="#cc0000" bgcolor="#ffffff"> - -<hr> - -<h3 ALIGN="CENTER">TAO Documentation</h3> -<div align="center"><center> - -<table cellpadding="10" cellspacing="8" border="10"> - <tr> - <td><font SIZE="+1"><dl> - <dt><a HREF="http://www.cs.wustl.edu/~schmidt/corba-research-realtime.html">Technical - Overview</a> </dt><P> - <dt><a HREF="http://www.omg.org/library/c2indx.html">OMG CORBA 2.x spec</a> </dt><P> - <dt><p><a href="../../docs/exceptions.html">Exception Handling</a></p> - <dt><a HREF="http://www.cs.wustl.edu/~schmidt/TAO/index.html">TAO Tutorials</a></dt><P> - <dt><a HREF="releasenotes/index.html">Release Notes</a> </dt><P> - <dt><a HREF="Tags.html">Tags and Magic Numbers</a> </dt><P> - </dl> - </td></font> - - <td><font SIZE="+1"><dl> - <dt><a HREF="components.html">ORB Configuration Options</a> </dt><P> - <dt><a HREF="compiler.html">TAO IDL Compiler Options</a> </dt><P> - <dt><a HREF="orbsvcs.html">ORB Services Directories</a> </dt><P> - <dt><a HREF="INS.html">Interoperable Naming Service</a> </dt><P> - <dt><a HREF="implrepo/">Implementation Repository</a> </dt><P> - <dt><a HREF="minimumTAO.html">Minimum TAO</a> </dt><P> - </dl> - </td></font> - </tr> -</table> -</center></div> - -<P><hr> - -<p>Back to the <a HREF="http://www.cs.wustl.edu/~schmidt/TAO.html">TAO</a> home page. <!--#include virtual="/~schmidt/cgi-sig.html" --> </p> -</body> -</html> diff --git a/TAO/docs/leader_follower.html b/TAO/docs/leader_follower.html deleted file mode 100644 index beb09eb92b3..00000000000 --- a/TAO/docs/leader_follower.html +++ /dev/null @@ -1,60 +0,0 @@ -<html> - <!-- $Id $ --> - <head> - <title>Implementation of leader follower model for global resources</title> - </head> - - <BODY text = "#000000" - link="#0000ff" - vlink="#cc0000" - bgcolor="#ffffff"> - - <body> - <HR> - <h1>Leader follower model for global resources</h1> - <HR> - <h2>Context</h2> - Global resources in TAO mean one ORB and using the reactive strategy - one Reactor. TAO uses the ACE Select Reactor for this purpose. - One main problem with multithreading and only one Reactor is that - only one thread can wait in handle_events at a time. - Handle_events is called, when a thread expects input, meaning - it is blocking to wait for it. - - <h2>Idea</h2> - One solution to this problem is to use a leader-follower model, - which partitions the set of threads wanting to wait for input - into one leader and followers. Every thread is eligible to become - a leader. A thread wanting to wait while nobody else is waiting - becomes the leader. If the leader gets its input, which is in - this case its response, it will select a new leader out of the - set of followers. The followers wait on a condition variable they - own and register it with the ORB core. The ORB core is thereby - responsible for making this access thread-save by providing - a lock for the list of followers with some flags, like - leader_available. - - <h2>Implementation</h2> - The above mentioned condition variables are owned by the - connection handlers, because reponses are expected per connection, - not necessarily, thinking about other resource models, per thread. - <p> - The involved classes are TAO_ORB_Core, TAO_Client_Connection_Handler - and TAO_ORB. In the TAO_ORB_Core class the list of followers, a lock, - a leader reference counter and a leader thread ID were added. - The handle_input and send_request methods on the TAO_Client_Connection_Handler - contain 95% of the code used for implementing the leader-follower - model. Care has to be taken, that the connection handlers are - suspended and resumed, properly. A special concern is that - no deadlocking occurs. - - <HR> - For more details and questions, - <p> - - <address><a href="mailto:mk1@cs.wustl.edu">Michael Kircher</a></address> - <p> - <address><a href="mailto:irfan1@cs.wustl.edu">Irfan Pyarali</a></address> - </body> -</html> - diff --git a/TAO/docs/locate_request.html b/TAO/docs/locate_request.html deleted file mode 100644 index 1978b2f3336..00000000000 --- a/TAO/docs/locate_request.html +++ /dev/null @@ -1,56 +0,0 @@ -<html> - <!-- $Id $ --> - <head> - <title>Implementation of locate requests</title> - </head> - - <BODY text = "#000000" - link="#0000ff" - vlink="#cc0000" - bgcolor="#ffffff"> - - <body> - <HR> - <h1>Locate requests</h1> - <HR> - <h2>Context</h2> - The CORBA specification describes locate requests as a way to - find out if an object is available at the other end of the wire - or not without invoking an actual method on it. - This way expensive marshalling and demarshalling can be prohibited. - Locate requests are part of GIOP. - - <h2>Implementation</h2> - The main classes involved in locate requests are the Server_Connection_Handler - to do check for the object. This is done by invoking the non standard - "non_existent" method on it. If it fails an exception will be thrown, - if the exception is not the Forward_Request exception of the POA, - the object is not there. If it is this specific exception, the new - forwarded location can be extracted and returned in the locate reply. - If the call on "non_existent" succeeds, we know the object is there and - return that. - - The client part of the locate request is handled int Locate_Request_Invocation. - The response is checked on the answer. If there, we go on and invoke the - actual method on the distant object. If not there, we fail and throw the proper - exception and if we get forwarded we replace our IIOP profile acordingly. - - <h2>API</h2> - To activate the locate requests, please invoke the non standard method - "_use_locate_requests (CORBA::B_TRUE)" on your CORBA::Object or any - object which inherits form this object. This will activate the locate - request on the first call to the object. The second time and on all - following calls "no" locate request will be used any more. To switch - it on again use "_use_locate_requests (CORBA::B_TRUE)" again. - You can also switch it of by "_use_locate_requests (CORBA::B_FALSE)". - - <HR> - For more details and questions, - <p> - <address><a href="mailto:irfan1@cs.wustl.edu">Irfan Pyarali</a></address> - <p> - <address><a href="mailto:mk1@cs.wustl.edu">Michael Kircher</a></address> - <p> - </body> -</html> - diff --git a/TAO/docs/minimumTAO.html b/TAO/docs/minimumTAO.html deleted file mode 100644 index c7e1429a2d2..00000000000 --- a/TAO/docs/minimumTAO.html +++ /dev/null @@ -1,248 +0,0 @@ -<!-- $Id$ --> - -<title> Minimum TAO </title> - - -<body text = "#000000" - link="#000fff" - vlink="#ff0f0f" - bgcolor="#ffffff"> - -<hr> -<p> - -<b> Minimum TAO </b> -<p> - -We have added support for the new <a href = -"http://www.omg.org/cgi-bin/doc?orbos/98-08-04.pdf"> <em> minimumCORBA -</em> </a> specification to <a href = -"http://www.cs.wustl.edu/~schmidt/TAO.html"> TAO</a>. The <em> -minimumCORBA </em> specification removes the following features from -the CORBA <a href = "http://www.omg.org/library/c2indx.html"> 2.2 </a> -specification. - -<ul> - -<li> Dynamic Skeleton Interface <br> -<li> Dynamic Invocation Interface <br> -<li> Dynamic Any <br> -<li> Interceptors <br> -<li> Interface Repository <br> -<li> Advanced POA features <br> -<li> CORBA/COM interworking <br> - -</ul> -<p> - -To minimize the footprint of TAO, we first <a href = -"http://www.cs.wustl.edu/~schmidt/ACE_wrappers/ACE-INSTALL.html"> -configure </a> ACE to support only those <a href = -"http://www.cs.wustl.edu/~schmidt/ACE_wrappers/docs/ACE-subsets.html"> -components </a> that are required by TAO. Secondly, we <a href = -"http://www.cs.wustl.edu/~schmidt/TAO/TAO-INSTALL.html"> configure -</a> TAO to only support the components specified by the <em> -minimumCORBA </em> specification. The following two tables show the -footprint reduction achieved. Note that the IDL Compiler column -refers to the code required to collaborate between the IDL compiler -and the ORB, and not to the code for the IDL compiler itself. - -<p> -<hr> -<p> - -<I> Note: All measurement are for ACE 4.6.29 and TAO 0.3.13 using -egcs-2.91.60 on SunOS5.7 <br> - -Make options used were: - -<code> debug=0 optimize=1 static_libs_only=1 DEFFLAGS=-DACE_USE_RCSID=0 </code> <br> - -The above make options translate into: - -(a) No debugging, -(b) Optimization is set to -O2, -(c) Static ACE and TAO libraries, and -(d) Use of RCS Ids is turned off. <br> - -<p> </I> - -<p> -<hr> -<p> - -<center><table cellpadding=4 border=4> - <tr> - <th>Configuration - <th>Component - <th>Total - <th>OS - <th>Utils - <th>Logging - <th>Threads - <th>Demux - <th>Connection - <th>Sockets - <th>IPC - <th>Svcconf - <th>Streams - <th>Memory - <th>Token - <th>Other - <tr> - <th rowspan=2>ACE (all components) - <th>Size, Kbytes - <td align=center>577.6 - <td align=center>11.5 - <td align=center>116.2 - <td align=center>14.0 - <td align=center>60.0 - <td align=center>40.0 - <td align=center>0.7 - <td align=center>13.7 - <td align=center>40.2 - <td align=center>101.5 - <td align=center>19.4 - <td align=center>20.9 - <td align=center>75.5 - <td align=center>64.5 - <tr> - <th>Percentage of<br>total size - <td align=center>100 - <td align=center>2 - <td align=center>20 - <td align=center>2 - <td align=center>10 - <td align=center>7 - <td align=center>0 - <td align=center>2 - <td align=center>7 - <td align=center>18 - <td align=center>3 - <td align=center>4 - <td align=center>13 - <td align=center>11 - <tr> - <th rowspan=2>ACE (TAO components) - <th>Size, Kbytes - <td align=center>437.4 - <td align=center>11.5 - <td align=center>116.2 - <td align=center>14.0 - <td align=center>60.0 - <td align=center>40.0 - <td align=center>0.7 - <td align=center>13.7 - <td align=center>40.2 - <td align=center>101.5 - <td align=center>19.4 - <td align=center>20.9 - <td align=center>0.0 - <td align=center>0.0 - <tr> - <th>Percentage of<br>total size - <td align=center>100 - <td align=center>3 - <td align=center>27 - <td align=center>3 - <td align=center>14 - <td align=center>9 - <td align=center>0 - <td align=center>3 - <td align=center>9 - <td align=center>23 - <td align=center>4 - <td align=center>5 - <td align=center>0 - <td align=center>0 - <tr> - <th>Reduction - <th>% - <td align=center>24.3 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>100 - <td align=center>100 -</table></center><p> - -<hr> - -<p> - -<center><table cellpadding=4 border=4> - <tr> - <th>Configuration - <th>Component - <th>Total - <th>POA - <th>Pluggable Protocols - <th>Default Resources - <th>Interpretive Marshaling - <th>IDL Compiler - <th>ORB Core - <th>Dynamic Any - <tr> - <th rowspan=2>Complete TAO - <th>Size, Kbytes - <td align=center>862.0 - <td align=center>281.9 - <td align=center>14.6 - <td align=center>7.9 - <td align=center>68.7 - <td align=center>10.5 - <td align=center>347.1 - <td align=center>131.3 - <tr> - <th>Percentage of<br>total size - <td align=center>100 - <td align=center>33 - <td align=center>2 - <td align=center>1 - <td align=center>8 - <td align=center>1 - <td align=center>40 - <td align=center>15 - <tr> - <th rowspan=2>Minimum TAO - <th>Size, Kbytes - <td align=center>639.5 - <td align=center>207.2 - <td align=center>14.6 - <td align=center>7.9 - <td align=center>68.7 - <td align=center>10.5 - <td align=center>330.3 - <td align=center>0.0 - <tr> - <th>Percentage of<br>total size - <td align=center>100 - <td align=center>32 - <td align=center>2 - <td align=center>1 - <td align=center>11 - <td align=center>2 - <td align=center>52 - <td align=center>0 - <tr> - <th>Reduction - <th>% - <td align=center>25.8 - <td align=center>26.5 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>0 - <td align=center>48 - <td align=center>100 -</table></center><p> - -<p> diff --git a/TAO/docs/orbsvcs.html b/TAO/docs/orbsvcs.html deleted file mode 100644 index d8a02aac033..00000000000 --- a/TAO/docs/orbsvcs.html +++ /dev/null @@ -1,252 +0,0 @@ -<html> - <!-- $Id$ --> - <head> - <title>TAO's CORBA Object Services Documentation</title> - </head> - -<BODY text = "#000000" -link="#0000ff" -vlink="#cc0000" -bgcolor="#ffffff"> - - <body> -<HR> - <h3>TAO's CORBA Object Services Directory Hierarchy</h3> - - <P>The file and directory organization for TAO services can be - confusing at first glance (and even on subsequent ones to be - honest), - so we felt like some rationale and explanation of the directory - hierarchy was needed.</P> - - <P>For general sanity all TAO services files are located under - <CODE>$TAO_ROOT/orbsvcs</CODE>.</P> - - <P>It is expected that clients use more - than one service at the same time - (in fact some of the services already do, for instance the - <B>Event Service</B> uses the <B>Naming Service</B> and the - <B>Scheduling Service</B>). - For this reason all the services stubs are grouped in one - library. - This library is located in - <CODE>$TAO_ROOT/orbsvcs/orbsvcs</CODE>. - Usually the include path is only <CODE>$TAO_ROOT/orbsvcs</CODE>, - so files are included like this:</P> - -<P><CODE> -#include "orbsvcs/CosNamingC.h" -</CODE></P> - - <P>To simplify the IDL generation the skeletons are also on the - library, - this is not a problem for client programs and most services need - to link the library anyway - (since they use other services.) - Further, - the current support for collocation requires that clients link - the skeleton files anyway. - </P> - - <P>In the future we intend to use ACE Service Configurator to give - the users control over collocation of the services implementation. - As a first cut all the service implementations are included in the - orbsvcs library <CODE>$TAO_ROOT/orbsvcs/orbsvcs</CODE>. - Since there are serveral services and each one is implemented - using several files we have given a different directory to each - service. - This structure could also simplify a future split into several - libraries (if it proves necessary). - </P> - - <P>The complete list of directories is:</P> - - <P> - <TABLE BORDER="2" - CELLSPACING="2" - CELLPADDING= "0"> - <TR> - <TH>Service</TH> - <TH>Implementation Sub-directory</TH></TR> - <TR> - <TD>A/V Streams Service</TD><TD><CODE>orbsvcs/AV</CODE></TD></TR> - <TR> - <TD>Concurrency Service</TD><TD><CODE>orbsvcs/Concurrency</CODE></TD></TR> - <TR> - <TD>Event Service</TD><TD><CODE>orbsvcs/CosEvent</CODE></TD></TR> - <TR> - <TD>Real-time Event Service</TD><TD><CODE>orbsvcs/Event</CODE></TD></TR> - <TR> - <TD>LifeCycle Service</TD><TD><CODE>orbsvcs/LifeCycle</CODE></TD></TR> - <TR> - <TD>Logging Service</TD><TD><CODE>orbsvcs/Log</CODE></TD></TR> - <TR> - <TD>Naming Service</TD><TD><CODE>orbsvcs/Naming</CODE></TD></TR> - <TR> - <TD>Property Service</TD><TD><CODE>orbsvcs/Property</CODE></TD></TR> - <TR> - <TD>Scheduling Service</TD><TD><CODE>orbsvcs/Sched</CODE></TD></TR> - <TR> - <TD>Trading Service</TD><TD><CODE>orbsvcs/Trader</CODE></TD></TR> - <TR> - <TD>Time Service</TD><TD><CODE>orbsvcs/Time</CODE></TD></TR> - </TABLE> - </P> - - <P>Note that in the current version of TAO we still have standalone - binaries for some of the services. However, some applications - may want to control what process implements a particular service. - Therefore, it has proved useful for - debugging purposes to keep the most used services separated. - The binaries in question are located in - <CODE>$TAO_ROOT/orbsvcs</CODE>, and the list includes: - </P> - - <UL> - <LI>Concurrenty_Service</LI> - <LI>Dump_Schedule</LI> - <LI>LifeCycle_Service</LI> - <LI>CosEvent_Service</LI> - <LI>Event_Service</LI> - <LI>Naming_Service</LI> - <LI>Scheduling_Service</LI> - <LI>Trading_Service</LI> - <LI>Time_Service</LI> - <LI>ImplRepo_Service *(see below)*</LI> - </UL> - - <P>In the future we plan to use a single binary and ACE Service - Configurator and keep a single binary.</P> - - <P>The Implementation Repository is a unique service in that it - starts server executables, and it doesn't make sense to collocate - it in another server. Because of this, only the IDL files are - located in <CODE>$TAO_ROOT/orbsvcs/orbsvcs</CODE>. The other - files are all located in - <CODE>$TAO_ROOT/orbsvcs/ImplRepo_Service</code>.</P> - - <P>Finally the tests and example programs are located in - <CODE>$TAO_ROOT/orbsvcs/tests</CODE>; - once more each may involves more than a single binary, - so each one is kept in its own directory; - the following list describes the contents of each one: - </P> - - <P> - <TABLE BORDER="2" - CELLSPACING="2" - CELLPADDING= "0"> - <TR> - <TH>Test directory</TH> - <TH>Purpose</TH></TR> - <TR> - <TD><CODE>AVStreams</CODE></TD> - <TD>A complete A/V server and client.</TD></TR> - <TR> - <TD><CODE>Concurrency</CODE></TD> - <TD>Test the Concurrency Service.</TD></TR> - - <TR> - <TD><CODE>CosEC_Basic</CODE></TD> - <TD>Test the basic functionality of the standard Event - Service. - </TD> - </TR> - - <TR> - <TD><CODE>CosEC_Multiple</CODE></TD> - <TD>Simple example that connects multiple consumers and/or - suppliers to the standard event service. It can be used to - show how composing a standard event-service and the - real-time event service provides filtering capabilities. - </TD> - </TR> - - <TR> - <TD><CODE>EC_Basic</CODE></TD> - <TD>Test the basic functionality of the real-time Event - Service. - </TD> - </TR> - - <TR> - <TD><CODE>EC_Custom_Marshal</CODE></TD> - <TD>Show how the Real-time event service can send user - defined data using custom marshaling. - </TD> - </TR> - - <TR> - <TD><CODE>EC_Mcast</CODE></TD> - <TD>Multiple real-time event channels can communicate using - multicast, this example shows how to do it. - </TD> - </TR> - - <TR> - <TD><CODE>EC_Multiple</CODE></TD> - <TD>Connect two Real-time Event Channels using the - <CODE>EC_Gateway</CODE>, - measure latency, utilization and minimum spacing. - </TD> - </TR> - - <TR> - <TD><CODE>EC_Throughput</CODE></TD> - <TD>Measure throughput and latency for collocated and remote - real-time event services. - </TD> - </TR> - - <TR> - <TD><CODE>Event_Latency</CODE></TD> - <TD>Test the Real-time Event Service and measure end-to-end latency, - it also uses the Scheduling and Naming services.</TD></TR> - - <TR> - <TD><CODE>ImplRepo</CODE></TD> - <TD>Tests used to test the functionality of the - Implementation Repository Service.</TD></TR> - - <TR> - <TD><CODE>Logger</CODE></TD> - <TD>An example logging service using the Naming Service to - locate a factory.</TD></TR> - <TR> - <TD><CODE>Naming</CODE></TD> - <TD>This is an obsolete directory.</TD></TR> - <TR> - <TD><CODE>Property</CODE></TD> - <TD>Testing for the Property Service.</TD></TR> - <TR> - <TD><CODE>Sched</CODE></TD> - <TD>A test of the Scheduling Service.</TD></TR> - <TR> - <TD><CODE>Simple_Naming</CODE></TD> - <TD>A number of Naming Service tests: from very simple to more fancy.</TD></TR> - <TR> - <TD><CODE>Simulator</CODE></TD> - <TD>Prototype implementation of DOVE (DOVE Agent, DOVE - Browser, DOVE MIB, DOVE Application). The DOVE Agent - consists of the Event Channel, which is then connected to - a DOVE Browser implemented in Java.</TD></TR> - <TR> - <TD><CODE>Trading</CODE></TD> - <TD>Tests for the Trading Service.</TD></TR> - <TR> - <TD><CODE>Time</CODE></TD> - <TD> A test for the Time Service.</TD></TR> - </TABLE> - </P> - - <H2>SEE ALSO</H2> - - <P>You may you to check TAO - <A HREF="releasenotes/index.html">release notes</A> - for up to date information on status, changes, future work, etc.</P> - - <hr> - - <address><a href="mailto:coryan@macarena.cs.wustl.edu">Carlos O'Ryan</a></address> - </body> -</html> diff --git a/TAO/docs/poa_migration.html b/TAO/docs/poa_migration.html deleted file mode 100644 index bcb446b1d4d..00000000000 --- a/TAO/docs/poa_migration.html +++ /dev/null @@ -1,209 +0,0 @@ -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> - <TITLE>Migrating from the BOA to the POA</TITLE> - <!-- $Id$ --> -</HEAD> - -<BODY text = "#000000" -link="#0000ff" -vlink="#cc0000" -bgcolor="#ffffff"> - -<HR><P> -<H3>Migrating CORBA Applications from BOA to POA</H3> - -Starting with the CORBA 2.2, the Basic Object Adapter (BOA) has been -deprecated in favor of the <A -HREF="http://www.cs.wustl.edu/~schmidt/POA.ps.gz">Portable Object -Adapter</A> (POA). This document explains the changes required to -migrate CORBA applications based on the BOA to use TAO's POA -implementation, which is the only Object Adapter supported by TAO. -For more information on the benefits of the POA please see the <A -HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html">Object -Interconnection</A> columns written by <A -HREF="http://www.cs.wustl.edu/~schmidt/">Doug Schmidt</A> and <A -HREF="http://www.iona.com/hyplan/vinoski/">Steve Vinoski</a>. - -<h3>Contents</h3> -<ul> - <li><a href="#Client-side Changes">Client-side Changes</a> - <li><a href="#Server-side Changes">Server-side Changes</a> - <li><a href="#Reference counting Servants">Reference counting Servants</a> -</ul> - -<H4><a name="Client-side Changes">Client-side Changes</a></h4> - -<ul> -<li>Very little has changed. Thus, many applications require no changes.</li><P> -</ul> - -<h4><a name="Server-side Changes">Server-side Changes</a></h4> - -<UL> -<li><CODE>POA_init</CODE> is replaced with <CODE>resolve_initial_references("RootPOA")</CODE> followed -by a <CODE>_narrow</CODE> operation.</li><P> - -<li>The implementation no longer inherits from the client-side stub. -Instead, they inherit from <CODE>PortableServer::ServantBase</CODE>. -The implications of this are (a) if you want a object reference for -that, you must use the <CODE>_this</CODE> method.</li><P> - -<li>Object ID's are assigned by the POA unless you activate the -servant with a specific ID. <A -HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/performance-tests/Cubit/TAO/IDL_Cubit">IDL_Cubit</A> -has examples on how to do this.</li><P> - -<li>Unlike the BOA, the POA explicitly addresses the temporal nature -of servants and declares that a POA can service either transient or -persistent servants (not both). The root POA's (mandated, -unchangeable) policy is "transient". The implications of this are -that in order for a client to be able to manufacture an object -reference on its own and use that to access an object, the servant for -that object must be registered with a POA whose policy is -"persistent". Thus, you must create a child POA with that policy and -register the servant with that POA. NOTE: when the POA declares -something as "persistent", it is only stating that the key is valid -between different runs of the server; it makes no claims that state or -anything else is persistent.</li><P> - -<ul> - <li> Servants are not automatically activated, hence you must register - them by calling some of the <CODE>activate_object*</CODE> methods on a POA or - calling <CODE>_this</CODE> on the servant; with the latest you have no control on - the ObjectId (which sometimes is good), and the POA must support the - right policies (the RootPOA does).</li><P> - - <li>Servant constructors use to take a <CODE>const -char*</CODE> parameter to set - they object id, this is not needed now, in fact in many cases they use - to pass this argument to the skeleton class: this will fail -now.</li><P> </ul> This list is not intended to be exhaustive, but -should give you a good starting point. If you find things along the -way that change your applications and I didn't note them, please send -them to me. Perhaps we can work together on the ultimate migration -document. <P> </UL> - -<h4><a name="Reference counting Servants">Reference counting Servants</h4> - -The new POA/servant <a -href="ftp://ftp.omg.org/pub/docs/orbos/98-07-12.pdf">reference -counting rules</a> of the CORBA 2.3 spec are somewhat tricky. Here are -two main reasons why: <p> - -<ul> - -<li> If a servant is deleted without deactivating from the POA, the -application will crash because the POA will try to access the still -registered (but now non-existent) servant when the POA is destroyed. <p> - -The solution to this is to make sure that the servant is deleted after -the POA is deleted or make sure that the servant is deactivated from -the POA before the servant is deleted. </li> <p> - -<li> You cannot delete a servant which is the target of the current -upcall/request. A good example of this is the typical destroy() -method, usually written like this: - -<PRE> - -class TAO_Export TAO_Thread_Policy : public POA_PortableServer::ThreadPolicy -{ - void destroy (CORBA_Environment &ACE_TRY_ENV); -}; - -void -TAO_Thread_Policy::destroy (CORBA::Environment &ACE_TRY_ENV) -{ - PortableServer::POA_var poa = this->_default_POA (ACE_TRY_ENV); - ACE_CHECK; - - PortableServer::ObjectId_var id = poa->servant_to_id (this, - ACE_TRY_ENV); - ACE_CHECK; - - poa->deactivate_object (id.in (), - ACE_TRY_ENV); - ACE_CHECK; - - // Commit suicide: must have been dynamically allocated. - delete this; -} - -</PRE> - -The correct implementation is: - -<PRE> - -class TAO_Export TAO_Thread_Policy : public virtual PortableServer::RefCountServantBase, - public virtual POA_PortableServer::ThreadPolicy -{ - void destroy (CORBA_Environment &ACE_TRY_ENV); -}; - -void -TAO_Thread_Policy::destroy (CORBA::Environment &ACE_TRY_ENV) -{ - // - // Remove self from POA. Because of reference counting, the POA - // will automatically delete the servant when all pending requests - // on this servant are complete. - // - - PortableServer::POA_var poa = this->_default_POA (ACE_TRY_ENV); - ACE_CHECK; - - PortableServer::ObjectId_var id = poa->servant_to_id (this, - ACE_TRY_ENV); - ACE_CHECK; - - poa->deactivate_object (id.in (), - ACE_TRY_ENV); - ACE_CHECK; -} - -</PRE> - -One additional step required is to make the POA responsible for the -servant after it has been registered with the POA: - -<PRE> - - // Register with the POA. - PortableServer::ThreadPolicy_var result = new_thread_policy->_this (ACE_TRY_ENV); - - // Give ownership of this servant to the POA. - new_thread_policy->_remove_ref (ACE_TRY_ENV); - -</PRE> - -If you use the above approach of multiple inheritance, you must add -the following to your header file: - -<PRE> - -// This is to remove "inherits via dominance" warnings from MSVC. -// MSVC is being a little too paranoid. -#if defined (_MSC_VER) -# pragma warning (disable : 4250) -#endif /* _MSC_VER */ - -</PRE> - -To see the above example in detail, checkout <A -HREF="../examples/POA/Reference_Counted_Servant">TAO/examples/POA/Reference_Counted_Servant</A> -and/or <A HREF="../tao/POA.cpp">POA.cpp</A> and <A -HREF="../tao/POA.h">POA.h</A>. </li> <p> - -</ul> - -<hr><P> - -Back to the <A -HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/index.html">TAO -documentation</A> page. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> -</BODY> -</html> diff --git a/TAO/docs/reactivator.html b/TAO/docs/reactivator.html deleted file mode 100644 index e4abd9788ae..00000000000 --- a/TAO/docs/reactivator.html +++ /dev/null @@ -1,21 +0,0 @@ -<html> - -<head> -<title> TAO Reactivation Service </title> -<meta HTTP-EQUIV="Refresh" CONTENT="1;URL=implrepo.html"> -</head> - -<body text="#000000" link="#0000ff" vlink="#cc0000" bgcolor="#ffffff"> - -<hr> - -<h1>TAO Reactivator </h1> - -<p>Has moved to <a href="implrepo.html">here</a> as the Implementation Repository</p> - -<hr> - -<p>Back to the <a HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/index.html">TAO -documentation</a> page. <!--#include virtual="/~schmidt/cgi-sig.html" --> </p> -</body> -</html> diff --git a/TAO/docs/releasenotes.html b/TAO/docs/releasenotes.html deleted file mode 100644 index 21854918af1..00000000000 --- a/TAO/docs/releasenotes.html +++ /dev/null @@ -1,26 +0,0 @@ -<HTML> -<HEAD> - <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> - <META NAME="GENERATOR" CONTENT="Mozilla/4.03 [en] (X11; I; Linux 2.0.30_SMP i686) [Netscape]"> - <META HTTP-EQUIV="Refresh" CONTENT="1;URL=releasenotes/index.html"> - <TITLE>TAO Release Information and TODO List</TITLE> -</HEAD> -<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#000FFF" VLINK="#FF0F0F"> -<!-- $Id$ --> -<CENTER> -<H2> -Release Information for The ACE ORB (TAO)</H2></CENTER> - -<CENTER> -<H3> -Version 0.0.12</H3></CENTER> - -<CENTER> -<H3> -17-October-1997</H3></CENTER> - -<HR> - -This document has moved <a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/releasenotes/index.html">here</a>. - -</HTML> diff --git a/TAO/docs/releasenotes/OBV.html b/TAO/docs/releasenotes/OBV.html deleted file mode 100644 index b0d729c4179..00000000000 --- a/TAO/docs/releasenotes/OBV.html +++ /dev/null @@ -1,149 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> -<body text="#000000" bgcolor="#FFFFFF"> - - <head> - <title>Object-by-Value status</title> - <!-- $Id$ --> - </head> - - <body> - <center> - <h1><a name="orb"></a>Objects-by-Value</h1> - Point of contact: <a href="mailto: coryan@cs.wustl.edu">Carlos O'Ryan</a> - - <p>Last Update: $Date$</p> - </center> - - <p>Objects-by-Value (OBV) describes the new type, <CODE>valuetype</CODE>. - It is introduced in CORBA 2.3 - <br>(Core: - <a href="http://www.omg.org/docs/ptc/98-12-04.pdf">ptc/98-12-04.pdf - </a> Mapping to C++: - <a href="http://www.omg.org/docs/ptc/98-09-03.pdf">ptc/98-09-03.pdf</a>). - This first implementation was contributed from - <a href="mailto: kuepper2@uni-wuppertal.de">Torsten Kuepper</a>. - <CODDE>Valuetype</CODE>s are similar to IDL <CODE>struct</CODE>s extended with - these features: - <ul> - <li><p>Encapsulate state and operations with local implementation.</p> - </li> - - <li><p>Single inheritance from a <CODE>valuetype</CODE> and - multiple inheritance from abstract - <CODE>valuetype</CODE>s. Eventually support of an - interface.</p> - </li> - <li><p>References to other <CODE>valuetype</CODE>s, with the - possibility of NULL references or shared (aliased) references.</p> - </li> - </ul> - - <p><CODE>Valuetype</CODE>s will likely be used to implement - abstract datatypes (ADT)s that can be copied to another process. - All processes that use the <CODE>valuetype</CODE> must have an - implementation for it since CORBA does not support code - migration, a la Java RMI.</p> - - <a name="current"><h3>Current status:</h3></a> - - <ul> - <li><p>The IDL compiler understands <CODE>valuetype</CODE>, if - it was compiled with <CODE>IDL_HAS_VALUETYPE</CODE> - defined. New options of TAO's IDL are: <P> - <UL> - <LI>-Gv Enable OBV support - <LI>-Sv Disable OBV support (default) - <LI>-Wb,obv_opt_accessor Make accessor and modifier functions inline. - Overriding them is not allowed in this mode. - </UL> - <p><CODE>libTAO</CODE> must be compiled with <CODE>TAO_HAS_VALUETYPE</CODE>.</p> - </li> - <li><p><CODE>Valuetype</CODE>s can be used as arguments in CORBA invocations. - There is an example in - <A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/OBV/Typed_Events">$TAO_ROOT/TAO/examples/OBV/Typed_Events</A>. - <CODE>Valuetype</CODE>s could even reference other - <CODE>valuetype</CODE> objects (but without sharing). - </p> - </li> - </ul> - - <a name="issues"><h3>Known issues:</h3></a> - - <ul> - <li><p>No support for <code>TypeCodes</code> of - <code>valuetype</code> objects - </p> - </li> - - <li><p><CODE>Valuetype</CODE>s work only in conjunction with - compiled marshalling (<CODE>-Gc</CODE>, currently default for - <CODE>tao_idl</CODE>). - </p> - </li> - - <li><p>No support for <code>TypeCodes</code> of - <code>valuetype</code> objects. Hence moving it into an - <code>any</code> is not possible yet. - </p> - </li> - - <li><p><CODE>Valuetype</CODE>s can not be contained in other types like - <CODE>struct</CODE>, <CODE>union</CODE>, - <CODE>sequence</CODE> or <CODE>array</CODE>. - </p> - </li> - - <li><p>No support for sharing (aliasing). - </p> - </li> - - <li><p>Forward and typedef'd declaration does not work.</p> - </li> - - <li><p>Inheritance (support) from an ordinary interface - not implemented.</p> - </li> - - <li><p>No support for abstract interfaces. - </p> - </li> - - <li><p>No support for <CODE>valuebox</CODE>es - </p> - </li> - - <li><p>No support for fragmentation (chunking) of the marshalled - <CODE>valuetype</CODE> object. Hence no support for truncation or - custom marshalling.</p> - </li> - - <li><p>The marshal engine accesses the state members directly and - does not utilize the accessor/modifier functions. This not - like in the CORBA specs and needs a change. But the - optimized mode (<CODE>-Wb,obv_opt_accessor</CODE>) should be - unaffected of that. - </p> - </li> - - <li><p>Obtaining a repository id of a <CODE>valuetype</CODE> - is currently non-standard. Hashed repository ids are not - implemented. - </p> - </li> - - <li><p>The map of <CODE>valuetype</CODE> factories needs some - revision to provide proper locking. Currently the - registration of factories is best completed before - unmarshalling <CODE>valuetype</CODE>s. - There is one map of factories for the whole process. This - will once be changed to conform to the specs, which - suggests one per ORB. - </p> - </li> - </ul> - - <P><HR><P> - <a href="#toc">Back to TOC</a> - </body> -</html> diff --git a/TAO/docs/releasenotes/TODO.html b/TAO/docs/releasenotes/TODO.html deleted file mode 100644 index dfa7657dea7..00000000000 --- a/TAO/docs/releasenotes/TODO.html +++ /dev/null @@ -1,1923 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> -<HEAD> - <TITLE>TAO TO-DO List</TITLE> -</HEAD> - <BODY TEXT="#000000" BGCOLOR="#FFFFFF"> - <!-- $Id$ --> - <CENTER><HR></CENTER> - - <CENTER> - <H3>General TO-DO list for TAO</H3> - </CENTER> - - <P> - This document presents our TO-DO list for TAO. - Currently, the list is not very well organized or prioritized. - It started as a personal TODO list for Carlos, so it is biased - towards the Event Service and related components. - As more people get involved it will become more - organized. - </P> - <P> - Last Updated: $Date$ $Revision$ - </P> - - <HR> - <P> - <H3>Work in progress</H3> - </P> - - <OL> - <LI><P>The ORB should support server side and client side - interceptors - <BR>[ASSIGNED TO:] Nanbor - </P> - </LI> - - <LI><P>Implement an Implementation Repository for TAO. - <BR>[ASSIGNED TO:] Darrell. - </P> - </LI> - - <LI><P>Implement a nice example of the COS Event Channel, - showing how it can provide filtering when combined with the - real-time Event Channel. - <BR>[ASSIGNED TO:] Pradeep - </P> - </LI> - - <LI><P><B>EC:</B> Complete the implementation of the new EC, - specially generate the strategies and changes required to - support hard real-time behavior. - </P> - <P>The new EC does not update the dependencies in - the scheduling service. We should be able to strategize this - by the appropiate use of a <CODE>Filter_Builder</CODE> and - decorators for the regular filters. - <BR>[ASSIGNED TO:] Carlos - <BR>[STATUS] All the pieces are in place, but I have to - continue debugging it. - </P> - </LI> - - <LI><P>Implement the Interoperable Naming Service spec, - specially the new standard features to bootstrap the initial - object references in the ORB. - <BR>[ASSIGNED TO:] Vishal - <BR>[STATUS] He is making good progress, near completion by - now. - </P> - </LI> - - <LI><P>Improve the connection recycling strategies, for - instance, - several strategies are possible: limit the maximum number of - open sockets, probably with both HWM and LWM bounds, - with different policies to choose the socket to close (LFU, - MRU?); - or maybe be more aggresive and recycle a socket once - all the object references pointing to a server are closed. - The later approach could be easily implemented if each - IIOP_Object held a reference to the set of sockets opened to - a certain TCP/IP address. - <BR>[ASSIGNED TO:] Kirthika - </P> - </LI> - - <LI><P>If the connection to the server cannot be established the - right exception is <CODE>TRANSIENT</CODE>, not - <CODE>COMM_FAILURE</CODE>; this and other exception - inconsistencies have to be checked - <BR>[STATUS] Most of this work has been completed, there are - a few i's to dot and t's to cross, for example: - what is the right exception to raise when a - <CODE>write()</CODE> fails? The answer is - none, we must transparently retry the current profile, not - the next one. - <BR>[ASSIGNED TO:] Carlos - <BR>[STATUS] The path on the client side seems clean - now. The server side is still under revision. - </P> - </LI> - - <LI><P>Add support for timeouts and protocol attributes to the - ORB. - <BR>[ASSIGNED TO:] Carlos - <BR>[STATUS] Support for the Policy objects is present, but - we haven't implemented any of the Policy objects and, of - course, we don't use them. - </P> - </LI> - - </OL> - - <HR> - - <P> - <H3>Pending Tasks</H3> - </P> - - <H4>Performance optimizations</H4> - - <OL> - <LI><P>Location forwarding should be strategized since some - applications don't need this feature. - </P> - </LI> - - <LI>Further optimize the outgoing memory allocation by adding - support for message blocks allocated from a pool (the - Message_Block class itself not the Data_Block or the buffer it - contains). - <P></LI> - - <LI>Optimize twoways by delaying memory allocation for the - incoming data buffer, thus improving interleaving between the - client and server (the client does something useful before - starting to wait for the server). - The client could also deallocate the outgoing buffers before - waiting for the reply. - <P></LI> - - <LI>The data blocks and their buffers could be allocated in a - single operation, using the beginning of a buffer to contain - the data block and the rest of it to contain the actual buffer - <P></LI> - - <LI><P>For extremely low latency applications we could remove - some fields from the IIOP protocol, for instance: - <UL> - <LI>The first four bytes are always 'GIOP' - </LI> - <LI>In homogeneous environments sending the byte order is a - waste - </LI> - <LI>Fields like the <CODE>Principal</CODE>, the services - context list, the versions can also be removed - </LI> - </UL> - <BR>[STATUS] Most of this optimizations were implemented, - and can be enabled using the <CODE>-ORBgioplite</CODE> command - line option. - </P> - </LI> - - <LI><P>Once the memory for incoming data is taken from an - allocator we can implement different approaches to manage - that memory: - <UL> - <LI>The allocator is global, allowing applications to keep - the incoming buffer even after the upcall has finished. - </LI> - <LI>The allocator is TSS, giving maximum performance for - applications that do not wish to preserve the buffer - after the upcall. - </LI> - <LI>The allocator is a TSS cache for a global memory pool, - this tries to strike a balance, by practically eliminating - the locking on each allocator/deallocation. Some strategy - is required to return the memory to the global pool, - consider, for example, - an application that will always allocate memory from one - thread and deallocate it in another thread. - </LI> - </UL> - </P> - </LI> - - <LI><P>Optimize marshaling for <CODE>TypeCode</CODE>, by not - including the optional fields on the wire; - this fields are useful (in some cases), so they should be - present for the "on memory" representation. - </P> - </LI> - - <LI><P>In some cases it is possible to marshal a complete - structure in a single operation to allow this the structure - must have fixed size (in the CDR spec sense) and its memory - layout must match the CDR layout. - </P> - </LI> - - <LI><P>If all the arguments to an operation are fixed size then - the header can be sent before the rest of the data, if the - data is big enoug this can represent a performance - improvement (because we increase overlapping between client - and server); further if the arguments also have the proper - layout they can be sent without copying to a temporary - buffer. - </P> - <P>If the arguments are not fixed size the header could be - sent before, but two passes over the data will be required. - </P> - </LI> - - <LI><P>Use GIOP 1.1 fragments to minimize the buffer allocations: - the buffer could be fixed size and we simply send fragments - for each buffer. - </P> - </LI> - - <LI><P>Demarshaling and managment of Anys could be optimized, - they esentially keep a copy of the CDR stream, - but they could just keep a reference (and increase the - reference count). - </P> - </LI> - - <LI><P>Some uses of DSI can optimized also, - for instance, - if the application is simply going to forward the request to - another object there is no need to parse the arguments in - the CDR stream and decompose them in the arguments, - a single *big* CDR stream can be kept. - </P> - </LI> - - <LI><P>The CDR streaming classes compute the alignment on each - operation, but they could remember the alingment from the - previous insertion or extraction operation; saving a few - cycles but spending a little more memory. - </P> - </LI> - - <LI><P>Some applications cannot afford compiled marshaling for - all the stubs and skeletons, - the generated code size would be too big. - Yet some operations could be critical and require code as - efficient as possible; - a <CODE>#pragma</CODE> can be added to give users - fine-grained control over code generation. - </P> - </LI> - - <LI><P>A new spec for Dynamic Any has been published and will - probably be part of CORBA 2.4. There are a great many - changes, leaving almost no area of the current implementation - untouched. - - </OL> - - <H4>New features and Bug fixes</H4> - <OL> - <LI><P><B>EC:</B>The <CODE>Priority_Dispatching</CODE> strategy - is incomplete. - <BR>[STATUS] The latest round of changes completed the - implementation, but more testing is required before dropping - this task - </P> - </LI> - <LI><P><B>EC:</B>Implement a dispatching strategy that uses the - current thread priority or ID to dispatch the event. This - will let us use multiple queues at different priorities but - without any scheduling service. - </P> - </LI> - <LI><P><B>EC:</B>Implement a null filter for consumers that - correctly matches the events, this can be used to do all the - filtering on the suppliers for applications that do not - require correlation. - </P> - </LI> - <LI><P><B>EC:</B>Several tests must be added to the event - channel testsuite, for example: - <UL> - <LI>A throughput test (move from - <CODE>EC_Throughtput</CODE>). - </LI> - <LI>A latency test (move from - <CODE>Event_Latency</CODE>) - </LI> - <LI>A connection time test - <BR>[DONE] - </LI> - <LI>A test to verify filtering and correlation - </LI> - <LI>A test to timeouts - </LI> - <LI>A priority inversion test - </LI> - <LI>A test to measure CPU scalability - </LI> - <LI>A stress test for gateways and observers - <BR>[DONE] - </LI> - </UL> - </P> - </LI> - <LI><P><B>EC:</B>Should we provide strategies to enforce the QoS - publications and subscriptions? This could require - collaborations with the scheduling service and possibly it - is only useful for debugging real-time applications, but it - certainly seems interesting. - </P> - </LI> - - <LI><P><B>EC:</B> Optimize the updates to the SupplierFiltering - module, specially when it is a singleton: currently it - receives a <CODE>connected</CODE> call for each supplier, - event though one would be enough. - </P> - </LI> - - <LI><P><B>EC:</B> We need some strategy in the EC to periodically - flush out misbehaving suppliers and consumers. Examples of - misbehavior include: suppliers flooding the EC; - consumers or suppliers that are destroyed, but were not - disconnected; - consumers that are not accepting events (risking a - dead-lock); - etc. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> Support for the <CODE>version</CODE> - pragma, this also requires some changes in the - <CODE>_is_a()</CODE> implementation. - </P> - </LI> - - <LI><P><B>ORB: </B> Stress test the ORB in the presence of - exceptions, verifying that no resources are leaked, all - locks are released, etc. - </P> - <P>Note: small experiments indicate that everything is OK, and - several tests raise exceptions without problems, but we need - an intensive test of this features. - </P> - </LI> - - <LI><P><B>EC:</B> Automate EC multicast group usage. This probably - requires some kind of server that mantains the relation - between event type/source and the mcast groups. - <BR>[STATUS] The multicast map server was defined, an - example implementation that hardcodes the port, and casts - the event type into the mcast address was implemented. - <BR>[STATUS] An advanced example that uses multiple mcast - groups per process was developed; this example would be used - To test the required features for general mcast support. - <BR>[STATUS] The example is able to automatically join and - leave multicast groups, as the consumer set on a local EC - changes. - The test has been constructed to minimize resources, it only - uses one socket for outgoing multicast messages; - currently it uses only one socket for each local group of - multicast UDP addresses sharing the same port; - eventually more sockets may be needed, - as sockets have limits on the number of multicast groups - they can join. - </P> - </LI> - - <LI><P><B>EC:</B> The <CODE>TAO_EC_Gateway_IIOP</CODE> can be - required to subscribe for events by source, but the source - can be local instead of remote. - This is not a problem since the Event Channel supports - multiple supplier IDs, - but we could check the local publications and remove those - events from the Gateway publication and subscription list. - <BR>[STATUS] The task is a second order optimization and has - very low priority. - </P> - </LI> - - <LI><P><B>ORB: </B> Use the IIOP 1.1 profile info to pass QoS - info and use it to preserve end-to-end QoS. - <BR>[STATUS] The tagged component for encoding QoS - information was created, but the server does not create it, - neither does the client use that information. - </P> - </LI> - - <LI>The size of pre-allocated buffer for the outgoing CDR - streams is defined at compilation time; but if we use an - efficient enough allocator we could make its size configurable - via the svc.conf file. In any case the *second* (and - subsequent) buffers come out of the allocator, so their sizes - could be configured in the already mentioned file. - <BR>[NOTE] We have to be able to do this while minimizing the - number of calls to ORB_Core_instance() - <P></LI> - - <LI><B>IDL Compiler:</B> The operation tables do not need to be - statics, they could be created on creation of the first - servant of that type. - <P></LI> - - <LI><P>It seems that some memory is leaked from the ORB cached - connector; but Purify gets confused by the fact that TAO - dynamically loads libTAO, so it could be just a bogus report. - </P> - </LI> - - <LI><B>IDL Compiler:</B>Support for the <CODE>fixed</CODE> data - type in the IDL compiler - <P></LI> - - <LI><P>CDR stream support for <CODE>wchar</CODE> is flaky or at - least untested. - <BR>[STATUS] This is slowly beign implemented, and so are - codeset translators inside the CDR streams. - </P> - </LI> - - <LI>Add << and >> operators to the - <CODE>CORBA::Request</CODE> class, to simplify DII invocations - (this is an Orbix-sism). - The IDL compiler has to generate them for the user defined - types. - <P></LI> - - <LI><P><B>ORB:</B> - Add a -ORBlogfile flag so we can set the ACE_ERROR and - ACE_DEBUG output destination in all TAO applications - </P> - </LI> - - <LI><B>EC:</B> Call ORB_init() in the EC threads? - [The dispatching threads for Boeing] - <P></LI> - - <LI><B>EC:</B> Build an EC example that uses all the cool features - (multiple endpoints on each process, collocated EC and - Scheduling Service, Naming, etc.) - <P></LI> - - <LI><B>EC:</B> Extend the Concurrency Service (or create a new - one) that allow us to have global "barriers" to synchronize EC - startup/shutdown. - <P></LI> - - <LI><B>IDL Compiler:</B> The IDL compiler could generate a static - method to access the interface repository ID of a class. - <P></LI> - - <LI>The current scheme for the orbsvcs leaves the user without - control over collocation of servants, we need to move to a scheme - similar to the one in $ACE_ROOT/netsvcs. - <BR>[STATUS] The user can control collocation, but we need a - dynamic way to do it (or an example) that exploits the Service - Configurator. We also may need to split the library. - <BR>[STATUS] David added a mechanism to compile only the - services that we want. - <P></LI> - - <LI><B>EC:</B> Cleanup the IDL structures for subscriptions, - publications, etc. (in the EC). - <BR>[STATUS] Part of this was completed. The Header and - Payload of the events are clearly distinguished, now we need - to use only the Header in the Publication and Subscription - definitions. - <P></LI> - - <LI>Resolve the <CODE>Typecode::equal</CODE> dilemma: is it - structural or type equivalence? Or a mixin? - <BR>[STATUS] The correct interpretation seems to be: - <UL> - <LI>If the interface repository ID is not present and/or the - optional field name is not present then TypeCode::equal - should just test for structural equivalence. - <P></LI> - <LI>If the interface repository ID is present then type - structural equivalence is not enough - <P></LI> - <LI>The spec (2.2 or 2.3?) will add a - <CODE>equivalent</CODE> method to check for structural - equivalence modulo aliases - <P></LI> - </UL> - <P></LI> - - <LI><P>According to Vinoski and Henning the - <CODE>CORBA::Policy</CODE> objects are also locality - constrained. - I could not find a references in the spec.</P> - </LI> - - <LI><P>Exercise the insertion and extraction operators for - <CODE>Any</CODE> in the <CODE>Param_Test</CODE>, - for example, provide a new <CODE>-i dii_any_op</CODE> - testing mode. - </P> - </LI> - - <LI><P>Test <CODE>Any</CODE> with variable sized types, such as - structures that contain a string inside. - Jeff reports that there is a - problem when destroying Anys initialized with this types, - even if the IDL compiler generated <<= operator is - used. - <BR>[STATUS] Many of the services do this kind of thing, for - example the Trading service passes all kinds of data in - Anys. The current version seems to be working , so this is - not a high priority task. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> Include a regression test to verify - that <CODE>octet</CODE> is <B>not</B> a valid discriminator - for unions - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> CORBA 2.2 does not allow - <CODE>octets</CODE> as - constants, yet the IDL compiler does not complain about it. - </P> - </LI> - - <LI><P><P><B>IDL Compiler:</B> Verify that the typecode for - unions use a <CODE>octet</CODE> with value <CODE>0</CODE> - for the default discriminator. - </P> - </LI> - - <LI><P><B>ORB:</B> - Is the client side in TAO handling a - <CODE>CloseConnection</CODE> GIOP message properly? - <BR>[STATUS] The code has been inspected and seems correct - </P> - </LI> - - <LI><P><P><B>IDL Compiler:</B> In some platforms it may be - necessary to add an extra value to an enum to force it to be - 32-bits wide. - </P> - </LI> - - <LI><P><CODE>$TAO_ROOT/orbsvcs/tests</CODE> may require the same - hierarchy changes that were done in - <CODE>$TAO_ROOT/tests</CODE>. - </P> - </LI> - - <LI><P>Can <CODE>_duplicate()</CODE> raise an exception? - If so the mapping that we generate is not correct for - platforms without native C++ exceptions. - </P> - </LI> - - <LI><P><B>ORB:</B> - By default TAO disables Nagle's algorithm, this should be - an optional feature, otherwise TAO will perform poorly over - WANs. - <BR>[STATUS] An alternative: this could be fixed as part of - the real-time spec that introduces transport specific - policies. - </P> - </LI> - - <LI><P>Check that system calls like <CODE>recv()</CODE> and - <CODE>send()</CODE> are restarted if a signal is received by - the process while they are executing. - <BR>[STATUS] In general this is done by ACE, but there have - been bug reports related to this. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> The CORBA 2.3 spec clarifies the - scope of a - <CODE>#pragma prefix</CODE>: - the prefix is supposed to get cleared after each - <CODE>#include</CODE>, - also the statement -<PRE> -#pragma prefix "" -</PRE> - should clear the prefix. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> GPERF is generating a function for - each binary search table; - a generic function could be used, or at least we should add - an option to gperf to it receives that generic function as - an argument. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> We must also check that oneways do - not contain any <CODE>out</CODE> or <CODE>inout</CODE> - parameters. - </P> - </LI> - - <LI><P>Currently we use blocking writes for the request, we need - to change this so we use the Reactor to send the data - instead of blocking directly on the <CODE>writev</CODE> call. - </P> - </LI> - - <LI><P><B>ORB:</B> - When handling a forward request we may get forwarded to a - collocated object. - The typical scenario is a server that register with the - Implementation Repository: - if it creates an object reference to a local object the - object reference will be pointing to the ImplRepo and - potentially none of its profiles will match the local ones. - Trying to contact the ImplRepo will result in a - LOCATION_FORWARD exceptions (and/or a LocateReply) pointing - to the local endpoints, but now we should use collocation. - </P> - </LI> - - <LI><P><B>ImplRepo:</B> - How do the ImplRepo and pluggable protocols interact? What - if the ImplRepo is using a protocol that is not implemented - in the server? Or vice-versa? - </P> - </LI> - - <LI><P><B>ORB:</B> - Decouple the ORB from interpretive marshaling. This style of - marshaling will not be required for many applications, and - it increases the footprint significantly (around 10%). - The tasks required are: - <UL> - <LI>Write one class per marshaling operation (encode, - decode, skip, etc), instead of one class per type. - This way we can extract out the operations we don't use. - </LI> - <LI>The IDL compiler could generate a - <CODE>_tao_destroy</CODE> method, that would delete an - object through a <CODE>void*</CODE>. - Such an operation will allow us to implement - <CODE>Any</CODE> without the <CODE>deep_free</CODE> - operation. - </LI> - <LI>Optimize <CODE>append</CODE> to stop the recursion once - the source and destination CDR streams have the same - alignment. - </LI> - <LI>It seems like the <CODE>skip</CODE> operation is only - used in the <CODE>Any</CODE> support. - It may be possible to agressively reduce the footprint by - removing both <CODE>skip</CODE> and <CODE>Any</CODE>. - </LI> - <LI>Exceptions are marshaled using the interpretive engine, - there is no reason why the skeletons couldn't do that job. - </LI> - </UL> - </P> - </LI> - - <LI><P>Need to support CORBA::Bounds to be compliant with 2.3 - spec. - </P> - </LI> - - <HR></HR> - - <!-- Things below this point are "big" tasks" that --> - <!-- could require major work --> - - <LI><P><B>ORB: </B>Support IIOP 1.2 in the ORB</P> - </LI> - - <LI><P>Provide mechanisms to marshal arguments into a CDR - stream, Jon Biggar contributed his proposal to the CORBA 2.3 - RTF: -<PRE> -Issue 991: Operations to add to CORBA::ORB pseudo-object - -Proposal: - -[Note I have expanded the SerializedEncoding IDL type to include version -information, since we now have 3 versions of CDR!] - -The following operations should be added to the CORBA::ORB -pseudo-object: - -module CORBA { - interface ORB { - ... - typedef sequence<octet> SerializedData; - typedef unsigned long SerializedFormat; - - const SerializedFormat ENCODING_CDR = 0; - - struct SerializedEncoding { - SerializedFormat format; - octet major_version; - octet minor_version; - }; - - SerializedData serialize(in Any data, - in SerializedEncoding how); - Any unserialize(in SerializedData data, - in SerializedEncoding how); - SerializedData serialize_value(in Any data, - in SerializedEncoding how); - Any unserialize_value(in SerializedData data, - in SerializedEncoding how, - in TypeCode tc); - ... - }; -}; - -These operations provide a standard mechanism for serializing and -unserializing the data in an any, along with hooks to support new -encoding formats as they are needed. The type SerializedEncoding -indicates the encoding mechanism to use to serialize and unserialize the -data. The format field specifies what encoding rules to use when -serializing the data, and the major_version and minor_version indicate -what version of the encoding rules to use. - -The serialize and unserialize encode the TypeCode along with the value -so that the serialized data is self contained. The serialize_value and -unserialize_value version encodes the value without the TypeCode to save -space, but a TypeCode must be supplied to unserialize the data. - -Since the serialized data may contain no indication of machine dependent -issues such as byte order, the serialized data can only be guaranteed to -correctly be unserialized on the same ORB. The IDL any type should be -used to exchange information between ORBs. - -Data encoded using the ENCODING_CDR format will be encoded using CDR -encapsulation format. -</PRE> - - </P> - </LI> - - <LI><P>Add support for Smart Proxies to the ORB - <BR>[STATUS] The new implementation of collocation has the - roots for this. - </P> - </LI> - - <LI><P>The ORB does not have an interface repository</P> - </LI> - - <LI><P>Once the interface repository is in place we could add - support for CORBA script - </P> - </LI> - - <LI>The current scheme for Typecode (keeping a CDR buffer with - their representation) is broken; we should use classes for - each variant of a TypeCode; but initialization would be - complicated then. - <P></LI> - - <LI><P>Consider decompositions of the ORB that would allow - dynamically linked plug-ins, for example it should be easy to - dynamically load a pluggable protocol. - Other decompositions are harder, but still worthwhile looking - at: - <UL> - <LI>Dynamically load the support for costly features, as the - ImplRepo or Location Forwarding. - <P> - </LI> - <LI>Dynamically configure POA with or without support for - holding state. - <P> - </LI> - </UL> - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> Currently the IDL compiler creates an - operation table that - includes all the base classes operations; this permits the - generation of efficient code that does not rely in - dynamic_cast or the _downcast() method for Servants (which - compare strings, hence it is slow). - It could be interesting to implement the alternative approach - were the class only looks its own operations and then tries - the parent. This will reduce code size, but will probably - decrease performance. - </P></LI> - - <LI>Server_Request objects in TAO are magical, the _duplicate() - method returns 0 and release() does nothing. - The problem starts because Server_Request is allocated from the - stack (to speed up things), hence reference counting would be - useless. Adding a clone() method will work better, but the - Server_Request holds pointers to several positions in the CDR - stream, we could clone the CDR stream, but a normal - Server_Request does not own it.... In our opinion (Carlos and - Irfan) we need not worry about this until we find a use case for - it. - <P></LI> - - </OL> - -<HR><P> - <H3>Completed Tasks</H3> - - <OL> - <LI><P>The current implementation of collocation is optimal for - hard-real-time - applications, but in some cases it may be desirable to follow - the normal execution path yet minize costs for collocated - calls. - An example would include an application that activates the - objects on demand. - It would be interesting to have a half-collocated stub - implementation, that will marshall the request and then - invokes the normal path on the "server" side, but without - crossing the kernel boundary. Ideally even the serialization - could be minimized or avoided. - <BR>[DONE] The ORB supports collocation through the POA. - </P> - </LI> - - <LI><P>The CORBAlite RFP is very interesting IMHO we just need to - remove features from TAO to make it a CORBAlite - implementation. The problem is how to keep the full blown - CORBA implementation also, this is an idea: - Write the TAOlite version of a class (example TypeCode):</P> - - <PRE> - class TAO_CORBAlite_TypeCode { - // Just the CORBAlite methods are implemented. - }; - </PRE> - - <P>Derive the full blown implementation:</P> - - <PRE> - class TAO_CORBA_TypeCode : public TAO_CORBAlite_TypeCode { - // Declare all the other methods. - }; - </PRE> - - <P>create two namespaces:</P> - - <PRE> - // in tao/CORBAlite.h - class CORBA { - tyedef TAO_CORBAlite_TypeCode TypeCode; - }; - - // in tao/CORBAfull.h - class CORBA { - typedef TAO_CORBAfull_TypeCode TypeCode; - }; - </PRE> - - <P>then (at compile time) the users chooses between the CORBAlite - or CORBAfull implementations:</P> - - <PRE> - // In $TAO_ROOT/tao/corba.h - #if USERS_WANTS_FAT_FREE_CORBA - #include "tao/CORBAlite.h" - #else - #include "tao/CORBAfull.h" - #endif - </PRE> - - <P>We need to consider how to support even smaller profiles that - the CORBAlite RFP, like removing <CODE>Any</CODE> or - <CODE>fixed<></CODE> support. - We also need to come out with a scheme to support - interpretive marshalling in the CORBAlite framework (where - TypeCodes don't have enough methods as to traverse them). - </P> - <P>[STATUS] The ORB can be compiled with support for CORBAlite - (aka Minimum CORBA). - </P> - </LI> - - <LI><P>Support the thread pool reactor in the ORB. - <BR>[ASSIGNED TO:] Nanbor. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> The TAO_IDL compiler does not handle - the following code sequence properly: -<PRE> - // IDL - interface Foo; - typedef sequence<Foo> FooSeq; - - interface Foo { - // anything here - }; -</PRE> - It may be necessary to have a multi-pass code generator to - solve this problem. - <BR>[DONE] Andy has completed the implementation of recursive - types. - </P> - </LI> - - <LI><P><B>ORB:</B> - Support multiple endpoints in the ORB. - Some interesting concurrency models (such as - thread-per-endpoint or thread-pool-per-endpoint) require - that we give an explicit name to each endpoint, and use - policies to match the thread with the endpoints it will - serve (and share). - <BR>[DONE] The ORB supports multiple-endpoints, mapping - threads to endpoints is in another entry. - </P> - </LI> - - <LI><P><B>EC:</B>The observer in the <CODE>TAO_EC_Gateway</CODE> - class is not properly deactivated. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B> Sometimes the Event Channel dead-locks during - shutdown. According to Ulf Jährig - <jaehrig@desys.com>, an easy way to reproduce the - problem is to run the EC_Throughput test under windows NT. - <BR>[STATUS] The test in question works perfectly on NT; it - looks like a race condition. Apparently this is only a - problem with the old EC. - </P> - </LI> - - <LI><P>The <CODE>TAO_Object_Manager</CODE> class needs an - assigment operator from <CODE>T_var</CODE>. - Either change the class to have two arguments or - use the <CODE>T::_var_type</CODE> trait. - We also have to change the class generated by the IDL - compiler. - Similar changes maybe required for the - <CODE>TAO_String_Manager</CODE> and the - <CODE>TAO_Object_Field</CODE> classes. - <BR>[DONE] Bala implemented this feature. - </P> - </LI> - - <LI><P><B>ORB:</B> - The implementation for the leader-follower - model on the client side has bug: - it will add the current thread to the follower list every - time it returns from waiting in the condition variable, - assuming that it was signaled and removed every time. - <BR>[STATUS] This is not a big problem because only a - warning is printed out. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>POA:</B> The <CODE>SINGLE_THREAD_MODEL</CODE> for the - POA requires that at most one concurrent call is invoked on - each servant in that POA. - <BR>[STATUS] Irfan is working on it as part of the POA - concurrency fixes. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> The methods on the server side - <B>must</B> have a throw spec, check CORBA 2.2, 20.35 - <BR>[DONE] Andy implemented this as part of the support for - native C++ exceptions. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> The IDL compiler should support - <CODE>#include "orb.idl"</CODE> properly. - IMHO it should not - add any <CODE>#include</CODE> to the generated code and the - <CODE>orb.idl</CODE> file should contain all the declarations, - except for the pseudo objects that are should be hardcoded - into the compiler. - <BR>[DONE] Jeff (and others?) implemented this feature, the - contents of the <orb.idl> file may need some work, but that - is easy to fix. - </P> - </LI> - - <LI><P><B>EC:</B> Debug interval computation in Linux (and NT?) - <BR>[DONE] There was a problem with the ACE_High_Res_Timer - initialization. - </P> - </LI> - - <LI><P><B>ORB:</B> - Support multiple calls to ORB_init(). - This requires several changes: - <UL> - <LI>Object references must keep an explicit reference to the - ORB that created them. In turn this requires that CDR - streams carry the ORB pointer for object reference - decoding. - <BR>[DONE] - </LI> - <LI>We must keep a table of ORB pointers based on the - <CODE>-ORBid</CODE> option. - <BR>[DONE] - </LI> - <LI>The hint on the cached connector has to be revised if - support for zero locks in the cached connector is going to - work. - <BR>[POSTPONED] The new cached connector implementation - will change this anyway. - </LI> - </UL> - </P> - </LI> - - <LI><P><B>IDL Compiler:</B>Support for unions with default cases - (implicit or explicit) - in the IDL compiler is incomplete. - <BR>[DONE] Andy implemented this features. - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> The IDL compiler front-end should be - case insensitive, - more precisely it should flag identifiers that only differ by - case as a conflict and verify that all uses of an identifier - have the same case. - <BR>[DONE] Jeff implemented this feature, there is an option - to disable it for backwards compatibility. - </P> - </LI> - - <LI><P>Support GIOP 1.1 in the ORB (fragments) - <BR>[DONE] The ORB should be able to receive GIOP - </P> - <P></LI> - - <LI>Support IIOP 1.1 in the ORB - <P></LI> - - <LI><P>Support native C++ exceptions. - This entails the following subtasks:<P> - <OL> - <LI>Create exceptions with the right dynamic type on the - client side. - For SII this should be simple: - the stub give us a list of the - possible user exceptions together with the factory methods - to allocate an exception of each type; - if the exception is not on that list we throw a - <CODE>CORBA::UNKNOWN</CODE>. - For DII we have to throw a - <CODE>CORBA::UnknownUserException</CODE>; - the user will receive the real exception inside an - <CODE>Any</CODE> then and she will have to extract it - either using the >>= operator or using the - forthcoming <CODE>DynAny</CODE>. - System exceptions are even easier, we always know how - to create them. - <BR>[STATUS] SII is working OK, we still need to complete - the support for DII. - <BR>[STATUS] The DII support was completed, but remains - untested. - <P></LI> - - <LI>Add the _raise() method to the exceptions. - <BR>[DONE] - <P></LI> - - <LI>On the server side: catch any CORBA exceptions thrown by - the upcall, and then transform that into the - proper <CODE>Reply</CODE> to the client side. - In the case of another C++ exception should we do - something? - <BR>[DONE] - <P></LI> - - <LI>On the client side, after creating the exception with - the right dynamic type we must invoke - <CODE>_raise()</CODE> on it. - <BR>[DONE] - <P></LI> - - <LI>Provide a TSS default value for the CORBA_Environment, - all the methods in the ORB library should use this - default. - <BR>[DONE] - <P></LI> - - <LI><B>IDL Compiler:</B> The IDL compiler should be able to - generate the - alternative mapping, but with the TSS default for the env - argument. - <BR>[DONE] - <P></LI> - - <LI><B>IDL Compiler:</B> The IDL compiler should generate the - standard mapping, without the environment argument. - <BR>[DONE] - <P></LI> - - <LI><P>In general we will need to complete and debug the - <CODE>TAO_TRY</CODE> macros; - they have limitations when dealing with the - alternative mapping, but are very useful. - <BR>[STATUS] This seems to be OK now, the code seems to - compile and work correctly now. - <BR>[STATUS] We need a new macro (TAO_TRY_THROW) to use - inside the TAO_TRY blocks, because TAO_THROW will not go - into the TAO_CATCH blocks, even if the exceptions match. - <BR>[STATUS] Nanbor implemented a much better set of - macros, that can be used with other ORBs, it is - implemented in <CODE>$ACE_ROOT/ace/CORBA_macros.h</CODE> - </P> - </LI> - - <LI>We need to test the ORB for resource leaking in the - presence of exceptions. - <P></LI> - - <LI>We <EM>could</EM> write portable server side code with - any of the mappings above if we use a macro for the env - argument, but the results are ugly: - <PRE> -// IDL -interface Foo { - void bar (in long x); -}; - -// C++ -class Foo { - void bar (CORBA::Long x TAO_ENV_ARG) - TAO_THROW_SPEC ((CORBA::SystemException)); -}; - </PRE> - note the missing comma before the TAO_ENV_ARG parameter. - <P> - </P> A different alternative is to generate both - functions, and make the default implementation just invoke - the other: - <PRE> -// IDL -interface Foo { - void bar (in long x); -}; - -// C++ -class POA_Foo { - void bar (CORBA::Long x, CORBA::Environment& env) - TAO_THROW_SPEC ((CORBA::SystemException)) - { - this->bar (x); - } - void bar (CORBA::Long x) - TAO_THROW_SPEC ((CORBA::SystemException)) = 0; -}; - </PRE> - The problem is: which alternative should be the pure - virtual function? Which one is overriden by the user? - <P></LI> - - </OL> - <BR>[STATUS] The main task ahead is to generate the conforming - mapping for the server side, i.e. remove the - <CODE>CORBA::Environment</CODE> argument and generate the - throw specs. - We need to wait for the compiled marshaling support to - implement this feature, otherwise the number of conflicts, - visitors and factories will grow without limit. - </P> - </LI> - - <LI><P><B>EC:</B>The new implementation of the EC does not send - <CODE>disconnect</CODE> messages on shutdown, this has to be - implemented. - <BR>[DONE] - </P> - </LI> - <LI><P><B>EC:</B> Use the Service_Configurator to dynamically load - the EC Module_Factory thus making it really configurable. - The same feature is needed for the new - <CODE>EC_Factory</CODE> class. - <BR>[STATUS] Notice that this is fairly easy to implement, - there doesn't seem to be much demand for it. - <BR>[DONE] In the new EC it is possible to load the - strategy factory. - </P> - </LI> - - <LI><P><B>EC:</B> The supplier filters could depend on the QoS - data, as consumer filters do. We should provide a factory - for them too. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B> We need to provide simple operations to update - the subscriptions of a consumer, as well as the publications - of a supplier, the current scheme (disconnecting and - connecting again) is inefficient. - <BR>[ASSIGNED TO:] Carlos - <BR>[DONE] - </P> - </LI> - - <LI><P><B>IDL Compiler:</B> Tom Ziomek - <tomz@cc.comm.mot.com> reports that the IDL - compiler does not verify that <CODE>oneway</CODE> operations - cannot include a <CODE>raise</CODE> expression. - <BR>[DONE] Andy fixed this. - </P> - </LI> - - <LI><P>The <CODE>_duplicate()</CODE> and <CODE>_narrow()</CODE> - functions can throw exceptions, yet our mapping does not - contain an <CODE>CORBA::Environment</CODE> argument. - A similar problem ocurs with - <CODE>ORB::resolve_initial_references</CODE>, the ORB can - throw the <CODE>InvalidName</CODE> exception. - <BR>[DONE] But the status of <CODE>_duplicate()</CODE> - remains, I added an entry for it. - </P> - </LI> - - <LI><P>The spec requires that strings as fields of structures be - initialized to the empty (not the null) string. - <BR>[DONE] Andy this this is the <CODE>String_Manager</CODE> - class. - </P> - </LI> - - <LI><P>The spec (CORBA 2.2, 20.17) defines accesor methods for the - fields of a <CODE>SystemException</CODE>. - <BR>[DONE] - </P> - </LI> - - <LI><P>Remove the unneeded methods from CORBA::Object - <BR>[STATUS] This task seems to be complete - <BR>[DONE] - </P> - </LI> - - <LI><P>Support the Sun bootstrapping mechanism for the Naming - Service - <BR>[STATUS] Replaced by the interoperable naming service - bootstraping. - </P> - </LI> - - <LI><P>Integrate the compiled marshalling approach. - <BR>[STATUS] Andy has made great progress on this. - <BR>[DONE] - </P> - </LI> - <LI><P>Verify the GPERF is working in all the relevant - platforms. - <BR>[STATUS] As far as we know it is working correctly. - <BR>[DONE] - </P> - </LI> - <LI><P>Integrate active demux of operations? - <BR>[STATUS] We use perfect hashing instead. - <P> - </LI> - - <LI><P>Several helper structs for <CODE>Any</CODE> have to be - added, mainly: <CODE>to_object</CODE>, <CODE>to_wchar</CODE>, - <CODE>to_wstring</CODE> and their <CODE>from_</CODE> - <BR>[DONE] Jeff added them to the Any class, later they were - moved to the CDR streaming classes because they are needed - there too. - </P> - </LI> - - <LI><P>Add a <CODE>corbafwd.h</CODE> header file to eliminate - the deep (and recursive) header dependencies in TAO. - <BR>[DONE] - </P> - </LI> - - <LI><P>In the collocated case the generated - <CODE>_narrow()</CODE> method calls the - <CODE>_create_stub()</CODE> method that allocates several - temporary objects. - <BR>[DONE] - </P> - </LI> - - <LI><P>For various projects, we need to produce a - minimal-footprint TAO ORB. One thing we could probably do - very easily would be to provide an #ifdef that will - conditionally omit the servant manager, POA manager, and - adapter activator features from TAO, along with all the - demuxing features that aren't active demuxing or perfect - hashing. - <BR>[DONE] Irfan implemented exactly this. We still have - room for more footprint size optimizations, but they are - second order things. - </P> - </LI> - - <LI><P>Add support for multiple Profiles in the ORB (completing - the IIOP 1.0 support) - <BR>[ASSIGNED TO:] Fred - <BR>[DONE] Fred added support for multiple profiles as part - of the pluggable protocols effort. - </P> - </LI> - - <LI><P><B>EC:</B> The current architecture of the real-time - Event Channel does not support some features, such as: - <UL> - <LI><P><B>EC:</B> Some applications are both suppliers and - consumers of events, - they may be interested in all the - events of type <B>T</B> unless the event is generated - by them. - </LI> - <LI><P><B>EC:</B> Can we factor out the scheduling service from - the EC? - </P> - </LI> - - <LI><P><B>EC:</B> The reactive event channel can eliminate - data copies because the data does not need to survive - after the <CODE>push()</CODE> call. - </P> - </LI> - - <LI><P><B>EC:</B> Many applications require to intercept - the EC event processing, for example to keep track of - the number of events received and sent. - This requires strategized factories for many (if not - all) of the Event Channel internal servants. - </P> - </LI> - - <LI><P><B>EC:</B> Some applications require ad-hoc - filters, such as "this events must arrive in - sequence", or "wait for all this events and then send - this other event". - </P> - </LI> - - <!-- This is Boeing specific --> - <LI><P><B>EC:</B> For some applications it is insteresting - to activate the EC servants (such as the - ConsumerProxys) in different POAs - </P> - </LI> - - </UL> - We have completed a new design for the real-time event - channel that will let us implement all this features (and - others). - <BR>[DONE] The new implementation is working, we have to add - several strategies and stress test it, but the architecture - seems sound. - <BR>[ASSIGNED TO:] Carlos - </P> - </LI> - - <LI><P><B>IDL Compiler:</B>The IDL compiler could generate files - with empty - implementation classes, just to make the life of implementors - a bit easier. - <BR>[DONE] - <BR>[ASSIGNED TO:] Yamuna - </P> - </LI> - - <LI><P><B>EC:</B> Build a COS Event Channel on top of the RTEC - Event Service. - <BR>[DONE] - <BR>[ASSIGNED TO:] Pradeep - </P> - </LI> - - <LI><P><B>EC:</B>Implement fragmentation and reassembly of UDP - messages. This is important for an effective implementation - of the multicast version of the EC. The classes affected - include <CODE>UDP_Receiver</CODE> and <CODE>UDP_Sender</CODE>. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B> The Event Channel must be profiled, - quantified, etc. - Now that we have a single threaded event channel this task - is much easier, the points to investigate are: - </P> - <P> - <UL> - <LI> How many data copies does the EC make? Can we reduce it - to zero? - </LI> - <LI> How many memory allocations? - <BR>[RESULT: 8] - <BR>Can they be replaced by memory pools? - </LI> - <LI>How many locks? - <BR>[RESULT: 29 (single threaded), 31 MT] - <BR>Can we strategize locks? - <BR>Can we share a single lock for the whole dispatch? - </LI> - </UL> - <BR>[ASSIGNED TO:] Carlos - </P> - </LI> - - <LI><P>The TypeCode internal (private) state needs locking, double - checked locking is needed to avoid excessive overhead, there - is potential for memory leaks if this locking is not used. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B>The <CODE>UDP_Receiver</CODE> class has some - problems on Win32 platforms because a - <CODE>recvfrom()</CODE> call fails if the buffer is to small - for the datagram, even if the <CODE>MSG_PEEK</CODE> flag is - used. We may need to modify the - <CODE>ACE_OS::recvfrom()</CODE> call to match the unix - semantics. - </P> - <BR>[DONE] Irfan fixed the <CODE>ACE_OS::recvfrom()</CODE> - function. - </LI> - - <LI><P><B>EC:</B> When shuting down a reactive Event Channel the - timeouts for the EC have to be cancelled. - It would seem like the proper way to do that is to do it in - the <CODE>shutdown()</CODE> method of the - <CODE>Timer_Module</CODE>. - <BR>[DONE] - </P> - </LI> - - <LI><B>EC:</B> Improve configuration support in the EC, give an - example of a single threaded EC, support different dispatching - strategies, etc. - <BR>[DONE] But there are a few bugs to remove. - <P></LI> - - <LI><B>EC:</B> Correlation in the EC has a bug [?] - <BR>[DONE] Added a correlation test into the EC_Basic test, - this does not mean that all bugs have been removed, but we - don't know of any remaining bugs. - <P></LI> - - <LI><P>The methods in <CODE>CORBA::TypeCode</CODE> should be - <CODE>const</CODE>. - </P> - <BR>[DONE] - </LI> - - <LI><P>Add the <CODE>CORBA::TypeCode::_tc_Bounds</CODE> and the - <CODE>CORBA::TypeCode::_tc_BadKind</CODE> type codes. - Currently they are in the wrong namespace (just - <CODE>CORBA::_tc_Bounds</CODE>). - </P> - <BR>[DONE] - </LI> - - - <LI><P>Add compiled marshalling - <BR>[STATUS] Andy is working on this. - <BR>[DONE] The compiled marshaling code works, we still have - to fine tune it a bit. - </P> - </LI> - - <LI><P>Implement the new DynAny types. - <BR>[STATUS] Jeff is working on this. - <BR>[DONE] More testing is needed, but the basics are - there. - </P> - </LI> - - <LI><P><B>EC:</B>The <CODE>TAO_EC_Gateway_IIOP</CODE> class - receives events from a "remote" EC and pushes them on the - local EC. - The subscription and publication list for the Gateway are - the disjunction of the local EC consumer subscriptions. - Unfortunately this can result in multiple supplier_IDs for - the Gateway, the current implementation is not prepared to - handle this. - The Gateway must keep a list of suppliers, each one with a - different supplier id, - when it receives a remote event it should push the event - only to the right supplier. - It must also keep another supplier used for the events that - are of interest by their event type, regardless of their - supplier ID. - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B>The Event Channel must be able to accept more - than one supplier with a given supplier ID, or at least we - should be able to configure the EC to work in such a mode. - This is required for some applications that treat the - supplier ID as a "supplier type". - <BR>[DONE] - </P> - </LI> - - <LI><P><B>EC:</B>If a Supplier disconnects while it has - consumers registered for it's Supplier_ID, - the consumers are not connected again even if the supplier - reconnects. - <BR>[DONE] - </P> - </LI> - - <LI><P>Further optimize memory allocation by using a memory pool - for the incoming CDR stream. - <BR>[DONE] The pool is configurable for the users that may - want to steal the CDR buffer. - </P> - </LI> - - <LI><P>The nested upcall support must be strategized, - some applications don't need this feature, - other applications are single threaded or use an - ORB-per-thread concurrency policy, - so using a full-blown leader follower in all cases can - result in a significant slow down. - It seems like the right way to - strategize this by changing the Client_Connection_Handlers. - <BR>[DONE] Irfan and Carlos are finished this task. - </P> - </LI> - - <LI><P>Use active demuxing in the POA to locate servants in - constant time, as well as active demuxing - in the skeletons to locate operations in constant time. - <BR>[DONE] Irfan finished this task. - </P> - </LI> - - <LI><P>Sometimes the ORB picks up the wrong name on multi-homed - hosts, - the <CODE>ACE_INET_Addr</CODE> class uses - <CODE>gethostbyaddr_r</CODE> to convert from the address into - a hostname, but it only uses the first alias. - <BR>[DONE] The current implementation tries to use the - alias that more closely matches the address of the given - host. - </P> - </LI> - - <LI><P>Many of the test programs in the - <CODE>$TAO_ROOT/tests</CODE> hierarchy are actually sample - programs or performance tests. - </P> - <P>We need to re-organize this hierarchy, following the ACE - scheme: - <UL> - <LI><B>tests</B> for programs that do regression testing. - </LI> - <LI><B>examples</B> for programs that illustrate how to use - TAO, a service or a component - </LI> - <LI><B>performace-tests</B> for programs that are used in - performance measurements - </LI> - </UL> - the same hierarchy may be needed in - <CODE>$TAO_ROOT/orbsvcs</CODE>. - <BR>[DONE] Doug did this changes already, minor revisions - many be necessary, and orbsvcs is still pending. - </P> - </LI> - - <LI>Cleanup memory managment in some of the servers, for - instance: Naming still believes that controlling the memory - for a stub will control the servants, this is not true - anymore. - <BR>[DONE] Marina fixed the Naming Service, the other services - are working OK also. - <P></LI> - - <LI><P>The mapping for the CORBA <CODE>boolean</CODE> type does - not require the <CODE>CORBA::TRUE</CODE> constant, - but it never mentions the <CODE>CORBA::B_TRUE</CODE> constant - either; in fact it recommends the usage of the literals - <CODE>0</CODE> and <CODE>1</CODE>. - We should move to use the <CODE>CORBA::TRUE</CODE> style, - because other ORBs offer the same feature, - but only use the literals, - to show the "Right Way"[tm] of doing CORBA things. - </P> - <BR>[DONE] Irfan removed the <CODE>CORBA::B_TRUE</CODE> and - <CODE>CORBA::B_FALSE</CODE> constants and replaced them with - the compliant <CODE>0</CODE> and <CODE>1</CODE> - </LI> - - <LI><P>Add an option to the IDL-compiler (e.g. -rp) meaning - "generate relative include paths". - <BR>[STATUS] Alex is working on this. - <BR>[DONE] - </P> - </LI> - - <LI><P>Add the <<= and >>= operators for - <CODE>CORBA::TypeCode</CODE> - <BR>[DONE] Jeff added the operators</P> - </LI> - - <LI>The IDL compiler should generate the code locally (not in - the directory where the .idl resides) or at least give an - option to do so - <BR>[DONE] Alex completed this, he even added an option to - select the output directory. - <P></LI> - - <LI>Are nested upcalls in different concurrency models, like - thread-per-connection working? - <BR>[STATUS] Irfan reports that this works correctly with - <CODE>thread-per-connection</CODE> - <BR>[DONE] The <CODE>NestedUpcall/Reactor</CODE> test is - giving the same results with either - <CODE>thread-per-connection</CODE> or <CODE>reactive</CODE> - strategies. - <P></LI> - - <LI>Normalize the compiled marshalling interface: the IDL - compiler is going to generate a different interface than the - code I showed in the EC_Custom_Marshal example; we need to - make all the code consistent so users have easy access to it. - <BR>[DONE] - <P></LI> - - <LI>Object references inside structures or sequences are not - decoded properly, the problem starts because the interpreter - expects a CORBA::Object_ptr, but the real type is a T_var; - virtual inheritance adds the last ingredient to the poison. - <BR>[STATUS] A possible solution is to use a T_manager_var that - has two fields a Object_ptr and a T_ptr.... - <BR>[DONE] The solution was to use - <CODE>TAO_Object_Field_T<T></CODE>, that - behaves like the _var classes, but extends them to provide - virtual methods to <CODE>_upcast()</CODE> and - <CODE>_downcast()</CODE> to and from - <CODE>CORBA_Object_ptr</CODE>. - Similar methods were added to sequences of objects. - <P></LI> - - <LI>Add options to the IDL compiler to set the suffixes. - <BR>[DONE] Alex finished this. - <P></LI> - - <LI>Support for 64bit longs in the IDL compiler - <BR>[DONE] They were supported already, but we had to test - them, I added a test to Param_Test. - <P></LI> - - <LI>The do_static_call() and do_dynamic_call() methods should - use an array of <CODE>void*</CODE> - (in the first case static and generated by the IDL compiler); - this will remove the problems with g++ and probably work - faster. - <BR>[DONE] - <P></LI> - - <LI>The IDL compiler gets confused with paths in NT, this may be - due to my changes to report errors correctly (coryan). - <BR>[STATUS] Creating a Win32 workspace to try it. - <BR>[DONE] - <P></LI> - - <LI>The current implementation of octet sequences based on - message blocks has a few problems, it cannot marshall - chains of message blocks properly. - Notice that complete support for chains of message blocks will - complicate the sequence of octets implementation (like - operator[]) and will make others either hard or expensive - (like get_buffer ()). - <BR>[STATUS] It seems like the best tradeoff would be to - support the chain during marshalling, but disable or give no - warranties for operator[] and get_buffer(). - <BR>[DONE] - <P></LI> - - <LI>Debug Memory Pools in the EC there seem to be a problem when - sending multiple events in a row (a memory leak, limit or - corruption). - <BR>[DONE] - <P></LI> - - <LI>Add suspend and resume operations to the PushConsumerProxy - and PushSupplierProxy interfaces, following the Notification - Service spec. - <BR>[DONE] - <P></LI> - - <LI>Optimize connection lookup in the client side, using "hints" - from the previous lookup, or keeping smaller sets on each IIOP - profile or a combination of both. - <BR>[STATUS] Irfan is working on - this. - <BR>[DONE] - <P></LI> - - <LI>Optimize the outgoing CDR streams by using TSS memory pools - for both the data blocks and the buffers. - <BR>[DONE] But we may consider strategizing the kind of allocator - we use (like using a free list instead of a generic - ACE_Malloc). - <P></LI> - - <LI>Optimize Octet Sequences. - <BR>[DONE] - <P></LI> - - <LI>Obtain results for the EC_Multiple test. - <UL> - <LI>Latency seems OK. - <P></LI> - <LI> Overhead: need lower priority for scavenger thread. - <P></LI> - </UL> - <P></LI> - - <LI>Debug EC_Multiple. - <P></LI> - - <LI>Your next assignment: Regenerate all methods in - _tao_collocated to avoid "inherit via dominance" warnings. - <BR>[STATUS] The IDL compiler was modified to generate a - suitable - <CODE>#pragma</CODE> that removes the warning, it reenables - the warning when leaving the file - <P></LI> - - <LI>Remove the SOLARIS2 macro from the TAO_IDL compilation. - <BR>[DONE] - <P></LI> - - <LI>Remove the preemption_prio message from Scheduling_Service. - <P></LI> - - <LI>The ORB core should be able to choose the right port for us - (in other words -ORBport 0) should work. - <BR>[DONE] - <P></LI> - - <LI>Client side optimization for Octet Sequences. - <BR>[DONE] - <P></LI> - - <LI>Minimize memory allocation in TAO - <BR>[STATUS] Down to 3 on the client side and 4 on the server - side. - <BR>[STATUS] For oneways it is down to 0 (for the common case) - on the client side and 2 on the server side. For twoways it is - 2 on both sides. - <P></LI> - - <LI>Automate subscription and publication list generation in the - EC_Gateway. - [VERY important for Boeing] - <BR>[STATUS] Completed and debugged, but the EC is still - buggy. - <P></LI> - - <LI>Debug EC shutdown and startup.... - [Specially startup for Boeign, but shutdown is important for - Purify and Quantify] - <BR>[STATUS] Shutdown is clean and startup of threads can be - controlled by the user. - <P></LI> - - <LI>Support a chain of Message Blocks in Output CDRs and use - writev() to write them. - <BR>[DONE] - <P></LI> - - <LI>Memory managment in the demarshalling engine, it is not - clear that the current scheme works in all cases (like - sequences of unions of anys). - We also need to fix sequences of object references: how does - the demarshalling engine learn about the dynamic type of the - objects? - Closely related to this is the problem of memory alignment for - different architectures, we need to develop strategies for each - one (they should only be a few) and choose the right one. - <BR>[STATUS] This seems to be working for most of the cases, the - main idea is to delay demarshalling until enough information - is available, for instance, when decoding an Any just a - reference to the CDR stream is stored, decoding actually - happens when the user invokes >>= on the any (at that point - all the info is there). - <P></LI> - - <LI>Add a new Profile type that includes the QoS info and using - for end-to-end QoS preservation. - [DEPRECATED] The IIOP 1.1 Profiles can handle that. - <P></LI> - - <LI>Show an example of the - <CODE>sequence<octet></CODE> and CDR streams. - <BR>[DONE] But the example could also include the marshalling of - plain C++ types. - <BR>[DONE too] - <P></LI> - - <LI>Test anys in the EC. - <BR>[DONE] Michael reported that they work OK on NT. - <P></LI> - - <LI>UDP for event channel and Multicast support in the EC. - <BR>[STATUS] Manual configuration using Suppliers and Consumers is - possible, automation is under research. - <P></LI> - - <LI>Unbind the EC and scheduling service from the Naming - Service. - <BR>[DONE] For the Event_Service and the examples. - <P></LI> - - <LI>Optimize oneways by not allocating the memory for the return - buffers. - <BR>[DONE] Added different Invocation classes for each case. - <P></LI> - - <LI>Fix the _non_existent call. - <BR>[DONE] The client side semantics match the new clarifications - of the C++ RTF, the server side is implemented by the IDL - compiler, though t could be a good idea to put that in the - POA. - <P></LI> - - <LI>Simplify EC configuration, a Factory class must provide the - Dispatching, Supplier, Correlation and any other Modules that - are required. - This is the right spot to add trivial Dispatching or - Correlation Modules and to dynamically load and configure the - EC. - <BR>[DONE] A Factory class is used to create the modules, only the - default factory is implemented so far. - <P></LI> - - <LI>Fix the ACE_Thread_Condition madness. - <BR>[DONE] We changed ACE so ACE_SYNCH_CONDITION expands to - ACE_Condition_Thread_Mutex - <P></LI> - - <LI>Reference counting should have locks, but we should remove - all the QueryInterface madness to make that work. The policy - for references in multiple threads is: the reference count - must be >2 if that happens. - <BR>[STATUS] The QueryInterface method (all the COM stuff for that - matter) was removed... - <BR>[DONE] - <P></LI> - - <LI>Reference counting for Typecodes is completely broken. - <BR>[DONE] - <P></LI> - - <LI>Under g++(2.7.2) the use of multiple inheritance in IDL - triggers some compiler bug, if the IDL explictly generated the - copy constructor for the skeletons (the POA_ classes) the - problem would go away. - <BR>[DONE] Fixed, Seth is testing the fixes and will commit them - soon (Tue Jul 21 14:24:56 CDT 1998) - <P></LI> - - <LI>The octet sequence optimization causes problems when Anys - get into the game. - <BR>[DONE] Seth reported that the problem was not real. - <P></LI> - - <LI>The DEEP_FREE method is also broken, sometimes we need to - release the top-level memory, sometimes not. - <BR>[DONE] We always release the memory in the Any, it was failing - due to weird interactions between the Environment containing - an exception and the Any that also did. - <P></LI> - - <LI>Improve error messages in the IDL compiler. - <BR>[DONE] At least the filename is correct now. - <P></LI> - - <LI>Support for arrays in the IDL compiler is incomplete, - specially anonymous arrays. - <BR>[DONE] According to Andy this is properly supported by the IDL - compiler now. - <P></LI> - - - <LI>Prepare the 0.2 release:<P> - <OL> - <LI>Execute all the tests in $TAO_ROOT/tests - </LI> - <LI>Run Param_Test (SII) and record what fails and what works. - </LI> - <LI>Run Param_test (DII) and record what fails and what works. - </LI> - <LI>Run Param_Test across Endian Borders. - </LI> - </OL> - <BR>[DONE] At last! - <P></LI> - - <LI>Move this list to the release notes. - <P></LI> - </OL> - -<HR> - -<P>Back to the TAO <A HREF="../index.html">documentation index</A>. <!--#include virtual="/~schmidt/cgi-sig.html" --> -</BODY> -</HTML> diff --git a/TAO/docs/releasenotes/ec.html b/TAO/docs/releasenotes/ec.html deleted file mode 100644 index 00a0b54f316..00000000000 --- a/TAO/docs/releasenotes/ec.html +++ /dev/null @@ -1,215 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> -<HTML> -<HEAD> - <TITLE>Event Service Status</TITLE> - <!-- $Id$ --> -</HEAD> -<BODY TEXT="#000000" BGCOLOR="#FFFFFF"> - -<H3>TAO's Real-time Event Service</H3> - Point of contact: <A HREF="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</A> - <H4>Last Updated: $Date$</H4> - -<H3>New on this release</H3> - - <UL> - <LI><P>It has been available for several releases now, but not - well documented. A complete re-implementation of the EC is - available, this implementation provides: - </P> - </LI> - <LI><P>The new EC allows the suppliers and consumers to update - their publications and subscriptions, they can simply call - the corresponding <CODE>connect</CODE> operation. - The default EC configuration disallows this, but it is very - easy to change it. - </P> - </LI> - <LI><P>The new EC uses an asbtract factory to build its - strategies, this factory can be dynamically loaded using the - service configurator. - </P> - </LI> - <LI><P>The new EC can use trivial filters for both consumers and - suppliers, resulting in optimal performance for broadcasters. - </P> - </LI> - <LI><P>Most of the locks on the new EC are strategized. - </P> - </LI> - <LI><P>The duration of all locks in the EC can be bounded, - resulting in very predictable behavior. - </P> - </LI> - <LI><P>More details can be found on the <CODE>README</CODE> file - in the <CODE>$TAO_ROOT/orbsvcs/orbsvcs/Event</CODE> - directory. - </P> - </LI> - </UL> - -<H3>Known issues:</H3> - - <DL> - <DT><I>The new EC does not use the scheduling service</I> - </DT> - <DD> - <P>The new implementation has been designed to simplify its use - in applications that do not require an scheduling service and - to minimize the code footprint when the scheduling service is - only required for dispatching - </P> - <P>To achieve this goals the EC will able to run without any - scheduling service or only consulting the schedule, but not - updating the dependencies. - </P> - <P>Using strategies and factories we will be able to - configure the EC to update the schedule only in the - configurations that required. - Unfortunately this features have not been implemented yet. - </P> - </DD> - - <DT><I>Further details:</I></DT> - - <DD><P>Many lower level issues and tasks can be found in the - <A HREF="TODO.html">TODO list</A>. - </P> - </DD> - </DL> - -<H3>Examples</H3> - - -For general documentation on the Event Service please read <A HREF="http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz">The -Design and Performance of a Real-time CORBA Event Service</A>. -<P>The simplest test for the Event Channel is <TT>Event_Latency</TT>, below -are the basic instructions to run it: -<OL> -<LI> -Compile everything under <TT>$TAO_ROOT/orbsvcs</TT>, this needs, obviously, -<TT>$TAO_ROOT/tao</TT> -and the IDL compiler in <TT>$TAO_ROOT/TAO_IDL</TT>.</LI> - -<P>Run the naming service, the scheduling service, the event service and -the test in <TT>$TAO_ROOT/TAO/orbsvcs/tests/Event_Latency</TT>. -As in: -<P><TT>$ cd $TAO_ROOT/orbsvcs</TT> -<P><TT>$ cd Naming_Service ; ./Naming_Service &</TT> -<P><TT>$ cd Event_Service ; ./Event_Service &</TT> -<P><TT>$ cd tests/Event_Latency ; ./Event_Latency -m 20 -j &</TT> -<P>You may want to run each program in a separate window. Try using a fixed -port number for the <TT>Naming Service</TT> so you can use the <TT>NameService</TT> -environment variable. -<P>The script <TT>start_services</TT> in <TT>$TAO_ROOT/orbsvcs/tests</TT> -can help with this. -<LI> -If you want real-time behavior on Solaris you may need to run these programs -as root; on the other hand, this particular example really has no priority -inversion, since only one thread runs at a time.</LI> -</OL> -Another example is <TT>EC_Multiple</TT>, numerous examples on how to run -this test can be found in the scripts located in <TT>$TAO_ROOT/orbsvcs/tests/EC_Multiple</TT>. - -<H3> -Features in previous releases</H3> - -<UL> - - <LI><P>Added fragmentation and reassembly support for the multicast - gateways</P> - </LI> - -<LI><P>Continued work on the multicast support for the EC, we added a new -server that maps the event types (and supplier ids) into the right mcast -group. Usually this server is collocated with the helper classes that send -the events through multicast, so using a CORBA interface for this mapping -is not expensive, further it adds the flexibility of using a global service -with complete knowledge of the traffic in the system, that could try to -optimize multicast group usage. -<P>The subscriptions and publications on a particular EC can be remotely -observed by instances of the <TT>RtecChannelAdmin::Observer</TT> class. -Once more using CORBA for this interface cost us little or nothing because -it is usually used by objects collocated with the EC. -<P><TT>TAO_EC_UDP_Receiver</TT> is a helper class that receives events -from multicast groups and dispatches them as a supplier to some event channel. -This class has to <B>join</B> the right multicast groups, using the <TT>Observer</TT> -described above and the <TT>RtecUDPAdmin</TT> to map the subscriptions -into multicast groups it can do this dynamically, as consumers join or -leave its Event Channel. -<P>When sending Events through multicast all the <TT>TAO_EC_UDP_Sender</TT> -objects can shared the same socket. -</P> -</LI> - -<LI><P>Added a prototype Consumer and Supplier that can send events though -multicast groups (or regular UDP sockets). -<P>The Event Channel can be configured using a Factory that constructs -the right modules (like changing the dispatching module), in the current -release only the default Factory is implemented. -<P>When several suppliers are consumers are distributed over the network -it could be nice to exploit locality and have a separate Event Channel -on each process (or host). Only when an event is required by some remote -consumer we need to send it through the network. -<P>The basic architecture to achieve this seems very simple, each Event -Channel has a proxy that connects to the EC peers, providing a "merge" -of its (local) consumer subscriptions as its own subscription list. -<P>Locally the proxy connects as a supplier, publishing all the events -it has register for. -<P>To avoid event looping the events carry a time-to-live field that is -decremented each time the event goes through a proxy, when the TTL gets -to zero the event is not propagated by the proxy. -<P>In the current release an experimental implementation is provided, it -basically hardcodes all the subscriptions and publications, we are researching -on how to automatically build the publication list. -<P>We use the COS Time Service types (not the services) to specify time -for the Event Service and Scheduling Service. -</P> -</LI> - -<LI> -<P>The <TT>Gateway</TT> to connect two event channels was moved from a test -to the library. The corresponding test (<TT>EC_Multiple</TT>) has been -expanded and improved. -</P> -</LI> - -<LI> -<P>The user can register a set of <TT>EC_Gateways</TT> with the <TT>EventChannel</TT> -implementation, the event channel will automatically update the subscription -list as consumers subscribe to the EC. -</P> -</LI> - -<LI> -<P>The code for consumer and supplier disconnection was improved and seems -to work without problems now -</P> -</LI> - -<LI> -<P>The <TT>Event_Service</TT> program creates a collocated <TT>Scheduling -Service</TT> this works around a problem in the ORB when running on -multiprocessor. -</P> -</LI> - -<LI> -<P>Startup and shutdown were revised, the event channel shutdown -cleanly now. -</P> -</LI> - -<LI> -<P>Added yet another example -(<TT>$TAO_ROOT/orbsvcs/tests/EC_Throughput</TT>), -this one ilustrate how to use the TAO extensions to create octet sequences -based on CDR streams, without incurring in extra copies. This is useful -to implement custom marshalling or late dermashalling of the event payload. -Future versions of the test will help measuring the EC throughput, hence -the name.</P> -</LI> -</UL> - -</BODY> -</HTML> diff --git a/TAO/docs/releasenotes/index.html b/TAO/docs/releasenotes/index.html deleted file mode 100644 index 992c629cd54..00000000000 --- a/TAO/docs/releasenotes/index.html +++ /dev/null @@ -1,1333 +0,0 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> - - <title>TAO Release Information and TODO List</title> -</head> -<body text="#000000" bgcolor="#FFFFFF"> -<!-- $Id$ --> -<center> -<hr></center> - -<center> -<h3> -Release Information for The ACE ORB (TAO)</h3></center> -Information is available on the following topics related to the <a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/VERSION">current -release</a> of <a href="http://www.cs.wustl.edu/~schmidt/TAO.html">TAO</a>: -<ul> -<li> -<a href="#idl">IDL Compiler</a></li> - -<li> -<a href="orbcore.html">ORB Core</a></li> - -<li> -<a href="#pp">Pluggable Protocols</a></li> - -<li> -<a href="#poa">Portable Object Adapter (POA)</a></li> - -<li> -<a HREF="../poa_migration.html">POA Migration Notes</a></li> - -<li> -<a href="../implrepo/index.html">Implementation Repository</a></li> - -<li> -<a href="#interfrepo">Interface Repository</a></li> - -<li> -<a href="OBV.html">Object-by-Value</a></li> - -<li> -<a href="#nservices">CORBA Naming Service </a>and <a href="../INS.html">Interoperable Naming Service</a></li> - -<li> -<a href="#tservices">CORBA Trading Service</a></li> - -<li> -<a href="#pservices">CORBA Property Service</a></li> - -<li> -<a href="#cservices">CORBA Concurrency Service</a></li> - -<li> -<a href="#av">CORBA Audio/Video Streaming Service</a></li> - -<li> -<a href="#ts">CORBA Time Service</a></li> - -<li> -<a href="#ec">CORBA Event Service</a></li> - -<li> -<a href="ec.html">TAO's Real-time Event Service</a></li> - -<li> -<a href="#scheduling">TAO's Scheduling Service</a></li> - -<li> -<a href="#logging">TAO's Logging Service</a></li> - -<li> -<a href="#apps">Test & Tests</a></li> - -<li> -<a href="#ace">ORB-related ACE Changes</a></li> - -<li> -<a href="#dove">The DOVE Demo</a></li> - -<li> -<a href="#forwarding">Location Forwarding</a></li> - -<li> -<a href="#leader">Global Resources and Leader-Follower Model</a></li> - -<li> -<a href="#locate">Locate requests</a></li> - -<li> -<a href="TODO.html">Our TODO list</a></li> -</ul> -A complete list of all modifications to TAO is available in the <a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/ChangeLog">ChangeLog</a>. -<p> -<hr> -<h3> -<a NAME="idl"></a>IDL Compiler</h3> -Point of contact: <a href="mailto:gokhale@research.bell-labs.com">Aniruddha -Gokhale</a> -<p>Current status: (As of June 12, 1999.) -<ul> -<li> -Generated code closely follows the C++ Mapping specified in the latest -C++ mapping for CORBA 2.3 (Document ptc/98-09-03).</li> - -<li> -IDL compiler is now able to generate code that support native C++ -exceptions on the stubs and skeletons. With this strict mapping, the -CORBA::Environment parameter is no longer generated. Use the -Ge flag -to get this functionality. -</li> - -<li> -We are now able to handle shared case labels and default label in -unions. In addition, whenever appropriate, we are also able to -generate the "default ()" operation. -</li> - -<li> -We are now able to handle recursive types. We are also able to -generate optimized typecodes. -</li> - -<li> -Struct members of type strings and arrays of strings now use the managed -type instead of the _var type. This change was necessary to conform to -the IDL->C++ mapping.</li> - -<li> -Fixed a large number of problems with anonymous arrays and sequences inside -structs and unions. The name of anonymous sequence needs to be fixed as -per latest C++ mapping spec.</li> - -<li> -Compile problems with sequence of forward declared interfaces is fixed. -In addition, problems with sequence of CORBA::Objects is fixed. In this -specific case, we were not generating the _downcast and _upcast methods.</li> - -<li> -Some more problems with the front-end have been fixed. In particular, oneway -operations with a "raises" clause or having an "inout", "out", or "return" -mode is flagged as an error.</li> - -<li> -For platforms that support namespaces, we now allow reopening modules.</li> - -<li> -Support for generating compiled marshaling code is added. Use the -Gc option. -However, this needs thorough testing before we can claim success. Unions -are still a problme with compiled marshaling.</li> - -<li> -The problem of "#include"ing the relative path of the header files rather -than the paths of their corresponding IDL files has been fixed. tao_idl -now generates #include path names that are derived from the IDL files that -are #include'd in the main idl file.</li> - -<li> -Added options to IDL compiler to specify file name endings for the IDL-generated -stubs, skeletons and the various header files. Please refer to the <a href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/compiler.html">IDL -compiler options</a> for details.</li> - -<li> -Added partial native C++ exception support:</li> - -<ul> -<li> -The ORB can be configured to catch native C++ exceptions thrown on the -server side and transmit them to the client side. On the client side exceptions -received from the wire are thrown using native C++ exceptions also.</li> - -<li> -To facilitate portability between the standard and alternative C++ mapping -the <tt>CORBA::Environment</tt> has a default value. The IDL compiler generates -code using that default value and the TAO library methods also have the -default.</li> - -<li> -Some macros are provided to facilitate portability between platforms with -and without macros.</li> -</ul> -There is still some work to do, mainly provide complete support for the -standard mapping, i.e. remove the <tt>CORBA::Environment</tt> argument -completely. -<li> -Verified support for the "long long" and "unsigned long long" datatypes. -On platforms that do not support 64 bit longs we provided <i>partial</i> -emulation through ACE_U_LongLong.</li> - -<li> Perfect Hashed Operation Lookup Strategy has been added to the -IDL Compiler. -P flag to <code>tao_idl</code> enables the perfect -hased lookup strategy. This strategy uses <a -href="http://www.cs.wustl.edu/~schmidt/gperf.ps.gz">GPERF</a>, the -GNU's Perfect Hash Function Generator written by Dr.Douglas -C. Schmidt. Right now, GPERF works only on Solaris. Any work on -porting GPERF to other platforms will be highly -appreciated.</L1></li> - -<li> -Significantly improved the support for unions. The default case is yet -to be handled.</li> - -<li> -Added support for TIE classes. If the interfaces are defined inside modules, -then the TIE class and its code gets generated inside a conditional macro. -For platforms that support namespaces, this macro will allow these TIE -classes else they get commented out. The reason to do this is because nested -templates have problems on most compilers.</li> - -<li> -The <<= and >>= operators for user-defined types are now generated.</li> - -<li> Completely redesigned the IDL compiler using the Visitor -patterns. Many incomplete issues have been resolved. These include -support for "sequence of typecodes", passing object references as in, -inout, and out parameters. Code generation for sequences is also -properly handled i.e., for a named sequence such as <CODE>typedef -sequence<char>CharSeq;</CODE>, we now generate a new class (and -hence a type) called "class CharSeq". Arrays are still being worked -out and will be done soon. An important difference in the generated -code is that the skeletons now use a table driven approach very -similar to the stubs.</li> - -<li> -Support for the "native" keyword added.</li> - -<li> -The problem of incorrect code generation for typedefs defined in an imported -file is resolved.</li> - -<li> -Problems when interfaces use single or multiple inheritance solved. The -problem was with the demultiplexing code, the generated operation tables, -and the dispatching mechanism. We are currently testing this with the Event -Channel code.</li> - -<li> -The problems arising due to public virtual inheritance when casting from -an interface class to CORBA::Object_ptr has been solved. We do this casting -inside the stubs/skeletons rather than first converting an interface class -pointer to a void*, storing it in an Any, and casting it to CORBA::Object_ptr -in the encode/decode methods. The casting inside the stubs/skeletons work -because the compiler has knowledge of both types.</li> - -<li> -Include files are handled properly. So are the definitions used inside -the include files that are used in the currently parsed files.</li> - -<li> -Generates C++ stubs and skeletons that use TAO's <a href="http://www.cs.wustl.edu/~schmidt/HICSS-97.ps.gz">interpretive -IIOP protocol engine</a>.</li> - -<li> -Support dynamic libraries on NT, i.e., marking classes for DLL export was -added. Two backend options control the name of the export macro, and the -name of an extra include file were the macro is defined; the options are -<tt>-Wp,export_macro=MACRO_NAME-Wp,export_include=INCLUDE_NAME</tt>.</li> - -<li> -The IDL compiler generates now source code for sequences. The user has -now the option to use these generated sequence classes or to use, as up -to now, the template instatiation. If TAO_LACKS_TEMPLATE_SPECIALIZATION -is defined, then template instantiation will be used, else not. The reason -for this was, that some C++ compilers did not support template instantiation -properly and sequences were based on templates. The generated source code -is mainly contained in the generated header file directly in the class -declaration.</li> - -<li> -The IDL Compiler generates templates for servant implementations. The options -are -GI [ h | s | b | e | c ]</li> -</ul> - -<p><br>Known bugs/unimplemented constructs: -<ul> -<li> -Generation of Managed types must somehow be moved to the ORB Core</li> - -<li> -We need support for ``TIEs'' (i.e., the object form of the Adapter pattern).</li> - -<li> -IDL is case-insensitive. However, it looks like our front-end is case-sensitive. -Thanks to Anil Gopinath (anil@ittc.ukans.edu) for pointing this out.</li> -</ul> -Future work: -<ul> -<li> -Need to relocate the various libraries used by the IDL compiler out of -the ACE directory. Having them here can cause problems when working with -multiple versions of TAO and a single version of ACE.</li> - -<li> -Fix bugs in the SunSoft IDL front-end we've uncovered. These primarily -include support for Unions.</li> - -<li> -Use <a href="http://www.cs.utah.edu/projects/flux/flick/">Flick</a> (from -the University of Utah) to generate compiled stubs.</li> - -<p>Goal is to measure the code size of the interpretive stubs generated -by TAO IDL compiler <i>vs</i> code size of compiled stubs. Then compare -the performance of each. We want to prove the thesis that TAO IDL compiler -generated interpretive stubs have a small code size, yet are comparable -in performance (or slightly less) than compiled stubs. Hence, it will be -useful for small distributed equipment such as handsets, PDAs, etc. -<p>In doing the above, improvements to the IIOP protocol engine in terms -of size/performance/determinism will be made. -<li> -Tweak the IDL compiler to generate code that's more easily integrated back -into the ORB Core, e.g., POA, etc. This will depend largely on our ability -to generalize the changes necessary to generated code.</li> - -<li> -The generated sequence classes should not be generated per sequence, but -per type and parent scope. Which means, that the overhead of having the -source code generated serveral times should be reduced. To do this, an -extra pass over the internal representation of the IDL file has to be done.<P> -</ul> - - -<hr> - -<br><!--#include virtual="orbcore.html" --> -<hr> -<h3> -<a NAME="pp"></a>Pluggable Protocols</h3> -Point of contact: <a href="mailto:fredk@cs.wustl.edu">Fred Kuhns</a> -<p>The goal of the pluggable protocol effort is to (1) identify logical -communication layers in the ORB, (2) abstract out common features, (3) -define general interfaces, and (4) provide necessary mechanisms for -implementing different concrete ORB and transport protocols. TAO's pluggable -protocol framework will allow disparate communication mechanisms to be -supported transparently, each with its own set of requirements and strategies. -<p>For example, if the ORB is communicating over a system bus, such as -PCI or VME, and not all the features of GIOP/IIOP are necessary and a simpler, -optimized ORB and transport protocol can be defined and implemented. Similarly, -it should be straightforward to add support for new transport protocols -that use native ATM or shared memory as the underlying communication mechanism. -In all cases the ORB's interface to the application will remain compliant -with the OMG CORBA standard. -<p>There will be several stages of the development proccess: (1) basic -pluggable transport protocols framework, (2) support for multiple profiles, -(4) add example transport protocols, such as ATM and VME, and refine/optimize -the transport protocols framework, and (4) add support for pluggable ORB -protocols, e.g., replacements for GIOP. Each of these steps is outlined -below: -<ul> -<li> -<b>Basic pluggable transport protocols framework</b>: We have added -several Bridge classes that decouple the transport-specific details from -the rest of TAO's ORB Core. This allows us to isolate the details of how -messages are communicated at the transport layer in a few classes. This -design resulted in the restructuring of the ORB Core and how requests are -handled. For instance, there is now the concept of communication layers: -Objects (e.g., references, method invocations, etc.), ORB Messaging, Transport, -and Network. The Object layer is just the usual stubs and skeletons.</li> - -<p>The common interfaces have been defined in the new abstract classes -that form the core of TAO's pluggable protocol framework, e.g., -<tt>TAO_Connector</tt>, -<tt>TAO_Acceptor</tt>, -<tt>TAO_Profile</tt> -and <tt>TAO_Transport</tt>. Two new mechanisms for keeping track of supported -transport protocols are the -<tt>TAO_Connector_Registry</tt> and -<tt>TAO_Acceptor_Registry</tt>, -which are essentially Abstract Factories that produce the right types of -connector, acceptors, and transports. <p> -<li> -<b>Multiple Profile</b> - Support for more than one profile per object. -This is important since there may be several different ways to access an -object. Each profile for an object may encode information pertaining to -QoS, network and transport protocols, addresses or routes.<p> - -<li> -<b>Example Transport protocols</b>- The first example, aside from IIOP, that -has been implemented, UIOP, uses local IPC. Other interesting transport -protocols would be for ATM, Buses (VME or PCI), shared memory, TP4, GSMP, and -UDP/IP.</li> <p> - -<li> -<b>Pluggable ORB protocols</b> - This step will add support for ORB protocols -besides GIOP. In particular, we will explore lightweight protocols using -shared memory and system buses like PCI or VME.</li> -</ul> -Current Status: -<ul> -<li> - -The initial prototype of the basic framework to support pluggable transport -protocols has been compiled, linked and, tested against a recent version -of TAO. The standard TAO regression tests -<tt>MT_Cubit</tt>, <tt>Multiple_Inheritance</tt>, -<tt>CDR</tt> -and <tt>EC_Throughput</tt> were run successfully.</li><P> - -<li> - Multiple endpoint support in the ORB has been added. A - list of TAO_Acceptors is kept in the Acceptor - Registry. When the ORB needs to create an IOR it iterates - over all the acceptors to do so. Using either multiple - <code>-ORBEndpoint</code> options or several endpoints - separated by semi-colons ';', the user can specify what - addresses the ORB should use. Each endpoint is specified - in URL format (ex: <code>iiop://foo.bar.com:0</code>), - this format can be extended to support different - protocols. -</li><P> - -<li> - If the user does not specify a list of endpoints then the - ORB creates a default endpoint for each protocol - configured. -</li><P> - -<li> - Added support for multiple Connectors in the ORB, the ORB - finds the correct connector based on the tag for the - profile. -</li><P> - -<li> - Added support for multiple profiles in the IORs, when the - ORB demarshals an IOR it queries the Connector Registry to - create the right kind of profile for the known protocols. - If one of the protocols is unknown we create a special - profile class that can only be used for marshaling and - demarshaling, not communication. -</li><P> - -<li> - Enabled the UIOP protocol, this protocol uses local IPC - (aka UNIX domain sockets) as the transport mechanism. The - protocol is loaded by default. If no explicit - <code>-ORBEndpoint</code> option is used (ex: - <code>-ORBEndpoint uiop:///tmp/my_rendezvous</code>). - -</li><P> - -<li> - Protocols can be dynamically loaded into the ORB: The - default resource factory reads the protocol "names" from - its list of arguments. These protocol names are used to - load an abstract factory via the service configurator. - This factory can create acceptors or connectors on demand. - By default only IIOP and UIOP (if supported by the - platform) are loaded. -</li><P> - -<li> - -The service configurator is now used to load protocol factories. - -</li><P> - -<li> - The <code>-ORBHost</code> and <code>-ORBPort</code> - options are deprecated. The new <code>-ORBEndpoint</code> - option supercedes them. If the deprecated options are - used, the ORB issues a warning. The user should not - depend on the existence of these options in the future. -</li><P> - -<li> - The <code>-ORBPreconnect</code> option supports multiple - protocols using the same URL formats that - <code>-ORBEndpoint</code> does. Note that the old - <em><code>host:port</code></em> format is supported for - backwards compatibility, but the user should not depend on - the existence of this old format since it is now deprecated. -</li><P> - -<li> - The URL style object reference format has been updated to - conform with the format that <code>iioploc</code> - uses. The BNF specification for <code>iioploc</code> is: - -<blockquote><code> -<iioploc> = "iioploc://"[<addr_list>]["/"<key_string>]<br> -<addr_list>= [<address> ","]* <address><br> -<address> = [<version> <host> [":" <port>]]<br> -<host> = DNS-style Host Name | ip_address<br> -<version> = <major> "." <minor> "@" | empty_string<br> -<port> = number<br> -<major> = number<br> -<minor> = number<br> -<key_string> = <string> | empty_string<br> -</code></blockquote> - - In TAO, <code>iiop</code> URL style object references are - equivalent to <code>iioploc</code> URL style object - references. <code>uiop</code> URL style object references - have a similar syntax: - -<blockquote><code> -<uiop> = "uiop://"[<addr_list>]["|"<key_string>]<br> -<addr_list>= [<address> ","]* <address><br> -<address> = [<version> <rendezvous point>]<br> -<rendezvous point> = Valid Filesystem Path<br> -<version> = <major> "." <minor> "@" | - empty_string<br> -<major> = number<br> -<minor> = number<br> -<key_string> = <string> | empty_string<br> -</code></blockquote> - - Note that the key string delimiter for <b><code>uiop</code></b> - is a vertical bar `<b><code>|</code></b>' (the command line - "pipe" symbol) not a forward slash - `<code>/</code>'. A delimiter other than a - forward slash is needed to prevent ambiguities of - where the rendezvous point ends and where the key - string begins since both may contain forward - slashes in them. - - The <i>rendezvous point</i> for <code>uiop</code> is - any valid path and filename that the ORB has permission to - read and write to. However, UIOP rendezvous points have - the same restrictions that local IPC has. The following - are some guidelines that will help ensure successful use - TAO's UIOP pluggable transport protocol: - <blockquote><li> - To guarantee portability, local IPC rendezvous - points (including the path and filename) should not - be longer than 99 characters long. Some platforms - may support longer rendezvous points, usually 108 - characters including the null terminator, but - Posix.1g only requires that local IPC rendezvous - point arrays contain a maximum of <b>at least</b> - 100 characters, including the null terminator.<P> - - If an endpoint is longer than what the platform - supports then it will be truncated so that it fits, - and a warning will be issued.<P> - </li> - <li> - Avoid using <em>relative</em> paths in your UIOP endpoints. - If possible, use <b><em>absolute</em></b> paths - instead. Imagine that the server is given an - endpoint to create using <code>-ORBEndpoint - uiop://foobar</code>. A local IPC rendezvous - point called <code>foobar</code> will be created - in the current working directory. If the client - is not started in the directory where the - <code>foobar</code> rendezvous point exists then - the client will not be able to communicate with - the server since its point of communication, the - rendezvous point, was not found. On the other - hand, if an absolute path was used, the client - would know exactly where to find the rendezvous - point.<P> - - It is up to the user to make sure that a given UIOP - endpoint is accessible by both the server and - the client.<P> - </li> - <li> - It is important to be consistent in the use of - absolute paths and relative paths for rendezvous - points. The two types of paths should not be used - for the same endpoint. For example, if - <code>uiop:///tmp/foo</code> is specified as the - server endpoint and <code>uiop://foo</code> as a - preconnect for a client in <code>/tmp</code>, then - the preconnection may be established but it is - likely it won't be used since the endpoint and - preconnect are interpreted as different strings, - i.e. <code>/tmp/foo</code> and <code>foo</code> are - not the same, lexicographically. On the other - hand, if both the endpoint and the preconnect are - the same string then a preconnection will be - established and used successfully.<P> - </li></blockquote> - - The <code>-ORBEndpoint</code> option uses a syntax similar - to that of the URL style object reference shown above. - The only difference is that the object key delimiter and - the object key string are not specified.<P> -</li> - -<p> -</ul> - -Known Issues: - -<ul> -<li> -</ul> -Critical Work: - -<ul> -<li> -Complete support for multiple profiles.</li><p> - -<p> -</ul> -Future Work: -<ul> -<li> -Verify all of TAO's regression tests still work. This will be followed -by performing a suite of tests to compare performance of with the unmodified -TAO distribution. Also, we'll extensively retest TAO using Purify and -Quantify. -</li><p> - -<li> -In parallel, we will add support for multiple profiles.</li><p> - -<li> -Long term work will include adding support for pluggable ORB protocols, -as well as transport protocols. This way we can develop optimal messaging -and transport protocols for a given platform.</li> - -<p> -</ul> - -<hr> -<h3> -<a NAME="poa"></a>Portable Object Adapter (POA)</h3> -Point of contact: <a href="mailto:irfan@cs.wustl.edu">Irfan Pyarali</a> - -The POA associates servants with the ORB and demultiplexes incoming -requests to servants. <P> - -<p>Current Status: -<ul> -<li> -TAO supports the POA spec. This section will carry updates as available.</li> -</ul> -Known issues: - -<ul> - -</UL> - -Future work: -<ul> - -<li> Determine the degree to which we will support the full semantics -of remote objects on a collocated object. The spec mandates that -collocated object should behave <i>exactly</i> like remote objects, -but that means that request will have to be queued rather than calling -a method directly, and this could be hazardous to our quest for -real-time ORB status.</li><P> - -</ul> - -Recently completed work:<P> - -<ul> - -<li> ORB::shutdown now properly deactives all the POA -Managers. </li><P> - -<li> - -POA Managers in TAO were previously ignored in the request processing -path on the server. This is now fixed such that their state is checked -before dispatching the client request to the servant. Only if the -state is <CODE>ACTIVE</CODE>, is the request dispatched to the -servant. Otherwise, the request is rejected. Since POA Managers start -off in <CODE>HOLDING</CODE> state, make sure to -<CODE>activate()</CODE> them before falling into the event loop. - -</li><P> - -<li> TAO's POA now properly supports both the threading policies: -SINGLE_THREAD_MODEL and ORB_CTRL_MODEL. </li><P> - -<li>The synchronization in the POA is now very optimal. For example, -the locks are not held across the invocation on the servant. The locks -are also not held across the invocation on the AdapterActivator and -ServantManagers. This allows us to use regular locks instead of -recursive locks inside the POA. This also allows multiple threads to -dispatch requests on the same POA simultaneous.</li><P> - -<li>TAO now supports reference counting between POA and servants, -including the new RefCountServantBase and ServantBase_var -classes. RefCountServantBase is a reference counted base class that -was added to the CORBA specification to avoid race conditions for -servant deletion in threaded servers. <a -href="ftp://ftp.omg.org/pub/docs/orbos/98-07-12.pdf">ftp://ftp.omg.org/pub/docs/orbos/98-07-12.pdf</a> -contains the relevant text. Check <a -href="../poa_migration.html#Reference counting Servants">here</a> on -some hints to avoid trouble.</li><P> - -<li> The POA now supports active demultiplexing of servants in the -SYSTEM_ID and the USER_ID policy. This should make the POA faster and -more predictable since there is no hashing involved and the index of -the slot where the servant is registered is in the Object Key.</li> -<P> - -<li> Previously, the complete POA name was used as the POA -identity. This scheme was inefficient in many ways including: (a) the -complete POA name can be significantly large in size, and therefore, -ineffient to pass with every method call from the client to the -server; (b) it is varible in size, and therefore, does not lend itself -to smart and effective parsing; (c) the searching based on the -complete POA name is very ineffient.</li> - -<p> The new solution is to use an active demux table, and flatten the -POA hierarchy. This will help in the searching since active demuxing -is fast and predictable. This will also help in the parsing since the -demux key will be fixed size. - -<p> Note that for persistent ids, we have to pass the complete POA -name in addition to the demux key in order to handle POA creation on -demand.<P> - -<li> There were some POA objects in a typical server that are not -freed up properly, resulting in a memory leak. This has now been -fixed.</li> <P> - -<li> Timestamps in persistent IORs were not required and have been -removed.</li> <P> - -<li> POA exceptions are not not system exceptions and have been -removed from the list of system exceptions.</li> <P> - -<li> Vastly improved the ability of the POA to deal with user -exceptions, memory allocation failures, and constructor failures.</li> -<P> - -<li> We now support a minimal POA for the minimal CORBA -specification.</li> <P> - -<li> We have decided not to support active demuxing for method name -lookup. The benefit of this optimization was questionable since the -current perfect hashing scheme provide very good and predictable -behavior.</li> <P> - -Also, note that this optimization will require many changes. We would -have to use the help of the IDL compiler to modify the object key that -is passed for every method call differently. Note that this scheme -doesn't work in the case of multiple inheritance or when the client -stubs are not TAO.<P> - -<li> Improved the parsing of object keys belonging to the -RootPOA. Since this is the default POA and is commonly used, we have -given it a reserved byte in the object key in order to quickly -identify it. With the reserved bit, the active demux key for the -RootPOA is not used, and no map lookups are required.</li> <P> - -<li> POA name separator was changed from '/' to '\0'. Since POA names -are strings, this makes a better choice since there is no chance of a -conflict with the string specified by the user. </li> <P> - -<li> We have support for reactivating servants with system generated -ids. </li> <P> - -<li> The TAO specific synchronization POA policy has been -removed. </li> <P> - -<li> New examples have been added to show how servants can be -dynamically loaded from DLLs on demand. </li> <P> - -<li> Support for collocation should be much better now because the POA -can tell if we created the object reference.</li><P> - -</UL> -<hr> -<h3> -<a NAME="interfrepo"></a>Interface Repository</h3> -Point of contact: <a href="mailto:parsons@cs.wustl.edu">Jeff Parsons</a><P> - -The Interface Repository provides run-time information about IDL -interfaces. Using this information, it is possible for a program to -encounter an object whose interface was not known when the program was -compiled, yet, be able to determine what operations are valid on the -object and make invocations on it using the DII. - -<p>Current Status: TDB -<p>Known Issues: TDB -<p>Recent Work: TDB -<p>Future Work: TDB -<p> - -<hr> - -<br><!--#include virtual="OBV.html" --> -<hr> - -<h3> -<a NAME="nservices"></a>CORBA Naming Service and Interoperable Naming Service</h3> -Points of contact: <a href="mailto:marina@cs.wustl.edu">Marina -Spivak</a> and <a href="mailto:vishal@cs.wustl.edu">Vishal Kachroo</a> -<p> - -The CORBA <a href="ftp://www.omg.org/pub/docs/formal/97-07-12.pdf"> -Naming Service</a> supports a hierarchical mapping between sequences -of strings and object references. The CORBA <A -HREF="ftp://ftp.omg.org/pub/docs/orbos/98-10-11.pdf">Interoperable -Naming Service</A> defines a standard way for clients and servers to -locate the Naming Service. It allows the ORB to be administratively -configured for bootstrapping to services not set up with the orb at -install time. <P> - -<p>Current status (as of 7th Apr 1999): -<ul> -<li> -Implementation of the CORBA Naming Service spec is complete. TAO's -Naming Service provides an optional persistence capability.</li> -<li> -Implementation of the CORBA InterOperable Naming Service is in -progress. </li> -</ul> -Recently completed work: -<ul> -<li> -Added support for Persistence (using memory-mapped files). Persistence -feature is optional, and is controlled by the command line argument.</li> - -<li> -Updated the implementation of the Naming Service to use new ACE -exception macros.</li> -<li> -Added support for the InterOperable Naming Service, which enables the -ORB to support IORs in user-friendly <CODE>iioploc</CODE> format. -These features allow the ORB to be configured to return arbitrary object -references from <CODE>CORBA::ORB::resolve_initial_references</CODE> -for non-locality-constrained objects. Two options -ORBInitRef and --ORBDefaultInitRef have been added to the orb for bootstrapping to -arbitrary services. -</li> - -<li>Added support for the Naming service to act like an agent: to understand IIOP -request messages from clients and respond with reply messages with a -LOCATION_FORWARD/OBJECT_NOT_EXIST status. The Naming Service can be -configured through ORB options to register arbitrary services given -the URL-format IOR for the service. The resolve_initial_references () -resolves a service in the following order : -<br>1. -ORBInitRef -<br>2. -ORBDefaultInitRef -<br>3. Multicast to service. -</li> - -<li> -Added a test for the InterOperable Naming Service that works in -conjunction with the current TAO examples. -</li> - -</ul> - -Work in progress: -<ul> - -<LI> Support for the iiopname format and conversions -to and from URL-style IORs. -</LI> - -<LI> -A detailed InterOperable Naming Service test. -</LI> - -</ul> -Future work: -<ul> -<li> -Support for a load balancing feature similar to the one present in ORBIX. -It will be possible to bind a group of objects under a single name, and when a client attempts to resolve the name in question, a preset policy (e.g., random, round robin, etc.) will determine which one of the object references from the group will be returned. -</li> -<li> -Support for the Naming Service to handle the IIOP -LocateRequest messages and respond with LocateReply messages with a -LOCATION_FORWARD/OBJECT_NOT_EXIST status. -</ul> - -<p> -<hr> -<h3> -<a NAME="tservices"></a>CORBA Trading Service</h3> -Point of contact: <a href="mailto:sbw1@cs.wustl.edu">Seth Widoff</a> - -<p>The <a href="http://www.omg.org/corba/sectrans.htm#trader"> Trading -Service</a> is an implementation of the COS Trading Service -speficiation that meets the Linked Trader conformance criteria --- it -implements the <tt>Lookup</tt>, <tt>Register</tt>, <tt>Admin</tt>, and -<tt>Link</tt> interfaces, but not the <tt>Proxy</tt> -interface. Notably, the TAO trader supports the following features:<P> -<ul> <li> Multithreaded operation;</li> - -<li> -Trader federations and distributed queries;</li> - -<li> -Dynamic properties;</li> - -<li> -Modifiable properties;</li> - -<li> -All policies described in the specification;</li> - -<li> -Preference sorting;</li> - -<li> -Service type inheritance hierarchies and subtype searching.</li> -</ul> -<a href="trader.html">Trading Service documentation</a> is also available. -<p>Future Work: -<ul> -<li> -The Proxy Interface.</li> - -<li> -Persistent storage of service types and offers.</li> -</ul> -<p> -<hr> -<h3> -<a NAME="pservices"></a>CORBA Property Service</h3> -Point of contact: <a href="mailto:alex@cs.wustl.edu">Alexander Babu -Arulanthu</a> - -<p>Current status (as of Mar 9th, 1999): All the interfaces of this -service have been implemented. Please -go through the test examples at $TAO/orbsvcs/tests/CosPropertyService. -Property Service is has been used by the TAO's <a href="#av">Audio Video Streaming -Service</a>developed for TAO. For general documentation of the -Property Service, please read <a -href="http://www.omg.org/corba/sectrans.html#prop">The Property Service -Specification.</a> - -<P>Recent Work: -<ul> - <li> - Changed the PropertyException from Exception to struct, according - to the OMG's changes. - </li> - <li> - Changed the implementation to allocate storage for the Sequence - out parameters, eventhough their length is 0. This is according - to the CORBA specification. - </li> -</ul> - -<p> -<hr> -<h3> -<a NAME="cservices"></a>CORBA Concurrency Service</h3> -Point of contact: <a href="mailto:tworm@cs.wustl.edu">Torben Worm</a> -<p>Current status (as of May 3rd): - -The <a href="http://www.omg.org/corba/sectrans.htm#concur"> -Concurrency Service</a> provides a mechanism that allows clients to -acquire and release various types of locks in a distributed system.<P> - -<ul> -<li> -A simple version of the Concurrency Service has been implemented, i.e. -a version without transactions. It is currently being tested.</li> -</ul> -Future Work: -<ul> -<li> -Implementation of the Concurrency Service with transactions</li> -</ul><P> -<hr WIDTH="100%"> -<h3><a NAME="av"></a>CORBA Audio/Video Streaming Service</h3> -Point of contact: <a href="mailto:naga@cs.wustl.edu">Nagarajan -Surendran</a> and <a href="mailto:yamuna@cs.wustl.edu">Yamuna Krishnamurthy</a> -<p>This is an implementation of the OMG spec addressing the <a href="http://www.cs.wustl.edu/~sumedh/research/corbaav.pdf">Control -and Management of Audio/Video Streams</a>.For more documentation on -TAO's A/V Service please have a look <A HREF="http://www.cs.wustl.edu/~naga/av.html">here</A>. - -<p><h4>Current Status:</h4> -<p> -<ul> - <li> - The audio/video streaming service has been implemented in the full - profile. The current implementation support all the flow related - components like flowEndpoint,FDev,FlowConnection,..,etc. - </li> - <li> - An MPEG-1 application which streams mpeg-1 video and mpeg-1 audio - separately has been developed using the service. The client side - of the mpeg player requires X windows support.Its available in - the release at $TAO_ROOT/orbsvcs/tests/AVStreams/mpeg/source. - </li> - <li> - An Integrated Video-on-demand application has been developed - using the Trading Service and the A/V Service. The demo uses a - Java FrontEnd and JNI to talk to the TAO C++ trader client. The - demo is available in the release at - $TAO_ROOT/orbsvcs/tests/AVStreams/server_discovery. - </li> -</ul> -<p>Work in progress: -<ul> -<li> -Implementing the SFP protocol. -</li> -<li> - Adding Multipoint streams support. -</li> -<li> - Developing a Video-conferencing application using the A/V Service. -</li> -</ul> - -<hr> -<p><a NAME="ts"></a><b>CORBA Time Service</b> -<p>Point of contact: <a href="mailto:vishal@cs.wustl.edu">Vishal Kachroo</a> - -<p> The <a href="ftp://ftp.omg.org/pub/docs/formal/97-02-22.pdf">Time Service</a> - allows clients to connect to Time Service Clerks and obtain globally -synchronized time. This time is calculated from the time obtained from -one or more Time Servers running on multiple machines in the -network. The service uses the TAO Implementation Repository to -activate the time servers on demand. - -<p>Current status (as of 10th Jan 1999): -<ul> -<li> -Implementation of a Distributed CORBA Time Service is complete.</li> -</ul> -Future work: -<ul> -<li> -Currently the average of the time obtained from the various servers is -considered the global notion of time. A better distributed time synchronization -algorithm can be used in the future.</li> - -<li> -Implementation of the Timer Event Service.</li> -</ul> -<p> - -<hr WIDTH="100%"> -<h3> -<a NAME="ec"></a>CORBA Event Service</h3> - -<h4> -Last updated: Fri Mar 5 20:38:26 CST 1999</h4> -Point of contact: <a href="mailto:pradeep@cs.wustl.edu">Pradeep Gore</a> -<p>The COS compliant Event Service implements the Event Service Specification: -<a href="http://www.omg.org/docs/formal/97-12-11.pdf">(.pdf)</a>, -<a href="http://www.omg.org/docs/formal/97-12-11.ps">(.ps)</a> -<br>This implementation is based on the Real Time Event service. -<h3> -Features in this release:</h3> - -<ul> -<li> -The Event Channel (<tt>$TAO_ROOT/orbsvcs/orbsvcs/CosEvent</tt>) supports -the <tt>push </tt>style event communication.</li> - -<li> -A simple test (<tt>$TAO_ROOT/orbsvcs/tests/CosEC_Basic</tt>) demonstrates -how to create and use the event channel.</li> - -<li> -Event Service (<tt>$TAO_ROOT/orbsvcs/CosEvent_Service</tt>)The Event Service -creates a COS compliant event channel and registers it with the naming -service with the default name "CosEventChannel".</li> - -<br>Please read the associated README for more details. - -<li> -CosEC_Multiple: <tt>($TAO_ROOT/orbsvcs/tests/CosEC_Multiple)</tt>: -This test demonstrates how multiple CosEC's connect to one RtEC and how -multiple consumers and producers exchange events in this configuration.</li> -</ul> -<h3> -Known bugs:</h3> -<ul> -<li> -CosEC_Multiple: <tt>($TAO_ROOT/orbsvcs/tests/CosEC_Multiple)</tt>: -Once the tests are done, the control doesn't return to the shell, -you have to say CTRL-C to get back to the prompt. -</li> -</ul> - -<hr WIDTH="100%"> -<!--#include virtual="ec.html" --> -<p> -<hr> -<h3> -<a NAME="scheduling"></a>TAO's Scheduling Service</h3> -Point of contact: <a href="mailto:cdgill@cs.wustl.edu">Chris Gill</a> -and <a href="mailto:levine@cs.wustl.edu">David Levine</a> -<p>Currently Implemented Features: -<ul> -<li> -The scheduling service can be built to use either a null implementation -or a strategized implementation of the configuration scheduler.</li> - -<li> -The null scheduler implementation, which is built by default, allows the -configuration scheduler to be used with applications that require a scheduling -service interface, but do not (at least in the current stage of their development, -in certain configurations, etc.) make use of the real-time scheduling features -it provides.</li> - -<li> -The strategized scheduler implementation can be built by #defining TAO_USES_STRATEGY_SCHEDULER, -and the appropriate scheduling strategy macro (TAO_USES_RMS_SCHEDULING, -TAO_USES_EDF_SCHEDULING, TAO_USES_MUF_SCHEDULING, or TAO_USES_MUF_SCHEDULING) -in $ACE_ROOT/ace/config.h. This allows the configuration scheduler to be -used with applications that require a specific scheduling strategy. Each -scheduling strategy will produce a set of static scheduling priorities, -which it will assign to operations based on their RT_Infos. For each static -priority, a strategy will also determine the run-time (dynamic) scheduling -strategy to use for that priority level.</li> -</ul> -Future work: -<ul> -<li> -Implement heap-based dispatching queues.</li> - -<li> -Add support for additional configurability, especially in the type -of dispatching strategy (list vs. heap) that will be used to dispatch operations -at a given static priority level.</li> - -<li> -Benchmark the various alternative strategies to obtain performance -profiles across different operation loads and OS platforms.</li> - -<li> -Add increased functionality. Requests and suggestions are welcome.</li> -</ul> - -<hr> -<h3> -<a NAME="logging"></a>TAO's Logging Service</h3> -Point of contact: <a href="mailto:mjb2@cs.wustl.edu">Matt Braun</a> -<p>Current status (as of August 4'th): -<ul> -<li> -The basic logging service has been implemented. It can log basic messages -from multiple clients. It is currently in the testing stage.</li> -</ul> -Future work: -<ul> -<li> -Add increased functionality. Requests and suggestions are welcome.</li> -</ul> - -<hr> -<h3> -<a NAME="apps"></a>Test & Performance Tests</h3> -Point of contact: <a href="mailto:naga@cs.wustl.edu">Nagarajan Surendran</a> -<p>Current Status: -<p>The TAO IDL_Cubit test application makes use of the Naming Service and -the server holds a TAO_Naming_Server component.Just running server and -client is enough to test the application. -<p>The various tests in the tests/POA test the different features of the -Portable Object Adapter interface like Explicit Activation, On Demand Activation,etc.. -<p>MT_Cubit: -<p>Current status: -<p>The TAO MT_Cubit test application is meant to serve as a starting point -for real-time tests on the TAO system. It comprises the following parts: -<ul> -<li> -<i>Server.</i> The server creates multiple CORBA objects (servants), each -with different real-time priorities. This priority is implemented by using -real-time thread support provided by the operating system. Thus, requests -sent to a high-priority servant are handled by a high-priority real-time -thread, and those sent to a lower priority servant are handled by correspondingly -lower priority threads.</li> - -<li> -<i>Client.</i> The client component binds to the servants, and sends a -stream of CORBA requests to the servants. It measures the response time, -i.e. the time taken for the request to complete successfully. In particular, -it measures the time taken for requests sent to the high priority servant -to complete. The volume of lower priority requests is configurable. The -client is thus able to measure the performance of the high-priority servant -in the presence of competition from several lower-priority servants.</li> -</ul> -Clearly, if the ORB endsystem handles the priorities of the various requests -correctly, increasing the volume of lower priority requests should not -affect the performance seen by the higher priority requests. The application -thus serves as a tool to measure and confirm this behavior. -<p>Future work: -<ul> -<li> -Study the impacts of scheduling & concurrency strategies on performance.</li> - -<li> -Evolve into a testbed for discovering sources of performance non-determinism -& priority inversion.</li> -</ul> - -<p>Pluggable: -<p>Current status: -<p>The TAO Pluggable test utilizes ACE Timeprobes to time the latency at -various points in the ORB, especially that incurred by the Pluggable Protocols -implementation. Comparisons can be made not only between different layers of the -ORB, but also between different protocols as they become available. -<p>Future work: -<ul> -<li> -Add options to redirect the output to a file.</li> -<li> -Script or otherwise automate the piping of the output to a spreadsheet.</li> -</ul> - -<hr> -<h3> -<a NAME="ace"></a>ORB-related ACE Changes</h3> -Points of contact: <a href="mailto:nanbor@cs.wustl.edu">Nanbor Wang</a> -and <a href="mailto:irfan@cs.wustl.edu">Irfan Pyrarli</a> -<p>Recently Completed Work: -<ul> -<li> -Added special declaration to OS.h for <tt>inet_ntoa</tt> and other functions -because VxWorks doesn't provide full argument prototypes for these library -functions.</li> - -<li> -The current caching connector behaves properly in the face of a non-blocking -connect request. The "fix" is simply to not support non-blocking connects -through the cache. When the <tt>connect()</tt> fails with <tt>EWOULDBLOCK</tt>, -morph the error to -1 and clean up the request.</li> - -<li> -Service handlers obtained from the caching connector are now cleaned up. -The application needs to be able to signal that it's not using it any longer, -and, when the application encounters an error, needs to effectively close -down that connection for good so that a new connection can be initiated.</li> - -<br>Added the ability for a Svc_Handler to recycle itself. idle() can be -called when the Svc_Handler is done serving a particular connection and -can how be recycled. The Svc_Handler now also has a pointer to a recycler -that is responsible for managing the connections. The recycler is usually -a Cached_Connector. -<br>Added new class ACE_Recycling_Strategy. It defines the interface (and -default implementation) for specifying a recycling strategy for a Svc_Handler. -This strategy acts as a consular to the Svc_Handler, preparing it for the -tough times ahead when the Svc_Handler will be recycled. -<br>Added new class ACE_NOOP_Concurrency_Strategy. It implements a no-op -activation strategy in order to avoid calling open on a recycled svc_handler -multiple times. -<br>ACE_Cached_Connect_Strategy now implements the ACE_Connection_Recycling_Strategy -interface. This allows Svc_Handlers to cache themselves with ACE_Cached_Connect_Strategy -when they become idle. It also allows them to purge themselves from the -connection cache when the Svc_Handlers close down. -<br>Also added ~ACE_Cached_Connect_Strategy that will cleanup up the connection -cache.</ul> -Future work: -<blockquote><i>None currently scheduled.</i></blockquote> - -<hr> -<h3> -<a NAME="dove"></a>The DOVE Demo</h3> -Points of contact: <a href="mailto:mk1@cs.wustl.edu">Michael Kircher</a> -and <a href="mailto:cdgill@cs.wustl.edu">Chris Gill</a>. -<p><a href="http://www.cs.wustl.edu/~schmidt/dove.html">DOVE</a> is documented -in detail <a href="http://www.cs.wustl.edu/~schmidt/Dove.ps.gz">online</a>. -This discussion focuses on the following goals: -<ul> -<li> -Have a DOVE Browser running using Java Beans as vizualization components.</li> - -<li> -Have the Event Channel as DOVE Agent running with an Event Consumer in -the DOVE Browser.</li> - -<li> -Having a DOVE Management Information Base (MIB), which dumps all events -transfered on the Event Channel into a file on persistent storage for later -reuse.</li> -</ul> -The DOVE Browser uses independent visualization components (Java Beans) -and the Event Channel as DOVE Agent. Connections can be established between -monitored metrics and the visualization components. -<p>We have three major components: Observables (monitored metrics), Observers -(a Java Bean for displaying the metric) and a DataHandler (for demultiplexing -the monitored metrics to the appropriate Observables). Each component inherits -from a base class, so that a certain behavior of the components can be -assured for each component. Relationships between components are based -on these base classes. -<p>The used Java Beans are required to conform to some standards, as they -have to support a function called "getProperty" which allows the DOVE Browser -to determine if the vizualization capabilities of a specific Java Bean -are sufficient to display the metric. A JavaBean is for example a Java -Panel which shows a Graph of the delivered doubles. So all metrics can -be displayed by this visualization component which can be expressed by -a single double. -<p>The DataHandler is connected to the Event Push Consumer (PUSH, because -we use the push concept of the Event Service). The Event Push Consumer -does not know what kind of data is transported. The only component knowing -all the details about the dependencies of the metrics is the DataHandler. -This separation allows easy extension and change of the demo. -<p><a href="http://students.cec.wustl.edu/~mk1/dove.html">Object Diagrams</a> -are available about this new concept. -<p>Event Service events are used as communication between DOVE Applications -and the DOVE Browser. The DOVE MIB analyses the event data field of all -events and stores this information into a file. The event data filed is -of type CORBA::Any and the DOVE MIB has no notion of what is conveyed in -this field. So the DOVE MIB has to discover the content via the embedded -type code information. Future work includes: -<ul> -<li> -Enhancing MIB functionality</li> - -<li> -Monitoring the AV Streaming Service</li> -</ul> -For more information on the DOVE demo, please refer to: $TAO_ROOT/orbsvcs/tests/Simulator/README.<P> -<hr> -<h3> -<a NAME="forwarding"></a>Location Forwarding</h3> -Point of contact: <a href="mailto:irfan@cs.wustl.edu">Irfan Pyarali</a>, -<a href="mailto:mk1@mk1.wustl.edu">Michael -Kircher</a>. -<p>For more information see <a href="../forwarding.html">Location forwarding</a> -<p> -<hr> -<h3> -<a NAME="leader"></a>Global Resources and Leader-Follower Model</h3> -Point of contact: <a href="mailto:irfan@cs.wustl.edu">Irfan Pyarali</a>, -<a href="mailto:mk1@mk1.wustl.edu">Michael -Kircher</a>. -<p>For more information see <a href="../leader_follower.html">Leader-follower -model</a> -<p> -<hr> -<h3> -<a NAME="locate"></a>Implementation of locate request</h3> -Point of contact: <a href="mailto:irfan@cs.wustl.edu">Irfan Pyarali</a>, -<a href="mailto:mk1@mk1.wustl.edu">Michael -Kircher</a>. -<p>For more information see <a href="../locate_request.html">Locate request</a> -<p> -<hr> -<p>Back to the TAO <a href="../index.html">documentation index</a>.<!--#include virtual="/~schmidt/cgi-sig.html" --> -</body> -</html> diff --git a/TAO/docs/releasenotes/orbcore.html b/TAO/docs/releasenotes/orbcore.html deleted file mode 100644 index b1256a8ddc3..00000000000 --- a/TAO/docs/releasenotes/orbcore.html +++ /dev/null @@ -1,434 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> -<html> -<head> -<title>ORB Core Status</title> -<!-- $Id$ --> -</head> -<body text="#000000" bgcolor="#FFFFFF"> - -<!-- *********************************** --> -<a name="toc"><h2>Table of Contents</h2></a> -<ul> - <li><a href="#current">Current Status</a> - <li><a href="#issues">Known Issues</a> - <li><a href="#ongoing">Ongoing work</a> - <li><a href="#future">Future Work</a> - <li><a href="#completed">Completed Work</a> -</ul> -<!-- *********************************** --> - -<hr> -<center> -<h1> <a name="orb"></a>ORB & ORB Core</h1> - -Point of contact: <a href="mailto: irfan@cs.wustl.edu">Irfan Pyarali</a> - -<p>Last Update: $Date$</p> -</center> - -<!-- ============================================================ --> -<a name="current"><h3>Current status:</h3></a> - -<ul> - <li><p>Trying to figure out a better <em>resource</em> management - scheme. <em>Resouces</em> here include ORB, POA, connections, - profiles.... that provide services for CORBA invocations. - </p> - <P>[STATUS]: The current version keeps very few objects - managed by the resource factory. Most are ORB specific. It - seems like the correct implementation is to make the few - remaining resources (such as the Reactor) a - per-ORB-per-thread entity. - </P> - </li> -</ul> - -<!-- --------------------- --> -<a href="#toc">Back to TOC</a> -<!-- --------------------- --> - -<!-- ============================================================ --> -<a name="issues"><h3>Known issues:</h3></a> - -<ul> - <li><p>When using the thread-per-connection concurrency model, if - some client leave the socket connection open without sending any - request, the server will crash on NT. This is because we are - doing a blocking recv when a server connection handler acts as - an active object, and the recv won't break out until the process - gets kill by the OS. This is especially a problem on NT because - on shutdown, NT close down the socket service, which cause the - blocking recv to unblock at which point, these threads try to - access the already destroyed ORB resources. A temporary - workaround is to close the sockets when the ORB is shutting - down. But this is not portable and only works on NT.</p> - </li> - - <li><p>Object references for objects dynamically created within a - server may not have proper host. When an object is dynamically - created and its object reference returned, it simply has to - "guess" at the host information that is returned in the IIOP - Profile. Currently, it guesses using the host name, which is a - reasonable guess in most cases. However, if there are multiple - interfaces on a machine <em>and</em> they have different host - names, it is possible that the desired effect will not be - realized, i.e., the connection to that new object may use a - different interface from the original object. Currently the only - way to change this is to use the <A - HREF="../Options.html#-ORBendpoint"><b>-ORBendpoint</b> option</a> to - manually specify that dynamically-created objects bind to a - specific interface so that their IIOP Profile has the desired - hostname. A more desirable fix is being investigated.</p> - </li> -</ul> -<!-- --------------------- --> -<a href="#toc">Back to TOC</a> -<!-- --------------------- --> - -<!-- ============================================================ --> -<a name="ongoing"><h3>Ongoing Work:</h3></a> - -<ul> - <li><p>ORB Core overhaul.</p> - </li> - - <li><p>Support new concurrency models, e.g., Thread-per-Request, - thread pool, etc..</p> - </li> -</ul> -<!-- --------------------- --> -<a href="#toc">Back to TOC</a> -<!-- --------------------- --> - -<!-- ============================================================ --> -<a name="future"><h3>Future work:</h3></a> - -<ul> - <li>Performance optimizations, such as:</li> - <ol> - <li><p>Replace all uses of <code>new</code> and <code>delete</code> - with allocators that can be put into TSS. The main - motivation for this is to eliminate lock contention when - multiple threads need to allocate/deallocate memory, - however it might also be possible to substitute an - allocator better-tuned to an application's specific - usage.</p> - </li> - </ol> - - <li>Robustness improvements:</li> - <ol> - <li><p>Improve connection cache so that it won't crash when - there are no more slots or sockets. - </li> - </ol> - - <li>New features:</li> - <ol> - <li><p>Implement <code>RT-CORBA</code> spec. once it passes - OMG member vote.</p> - </li> - - <li><p>Added support for CORBA Messaging Spec.</p> - </li> - - <li><p>According to tentative CORBA 2.3a spec, once - ORB::shutdown has been called, operation invocations on - object references obtained from this ORB must throw an - <code>BAD_INV_ORDER</code> exception.</p> - </li> - </ol> - - <li>Internal restructuring:</li> - <ol> - <li><p>Create some sort of internal "request" object which - carries enough context to suport deferred method - invocation such as one might find in the thread-pool - approach or wherever queuing might occur.</p> - </li> - </ol> - - <li>Documentation:</li> - <li><p>Writing up ORB restructuring notes.</p> - </li> - </ol> - - <li>Potential Optimizations:</li> - - <ol> - <li><p>There is a certain amount of overhead introduced by the - use of TSS Singletons. TSS singletons are very convenient - as the variable does not have to be passed from function - to function. Even though sort of access is generally - acceptable, the overhead of this approach maybe too high - when used in code which is executed frequently (e.g., - during an upcall). This critical code may have to be - restructured not to use TSS Singletons because of the high - overhead associated with it.</p> - </li> - </ol> -</ul> -<!-- --------------------- --> -<a href="#toc">Back to TOC</a> -<!-- --------------------- --> - -<!-- ============================================================ --> -<a name="completed"><h3>Completed Work:</h3></a> - -<!-- ************************************************************ --> -<!-- Please make sure you append new items at the end of the list --> -<!-- ************************************************************ --> -<ul> - <li><p><code>TAO_ORB_Core_instance()</code> returns the orb core - of the default orb (the first orb created by the user). This - may not be the orb that the user is interested in. The better - approach is <code>myorb->orb_core()</code>.</p> - </li> - - <li><p>Added an optional argument to resolve_initial_references() - that allows the user to specify a timeout (an upper bound - on the time-to-wait for a response from the ORB's multicast - "search" for a running server). If no timeout value is - specified by the user, - <code>TAO_DEFAULT_SERVICE_RESOLUTION_TIMEOUT</code> is - used.</p> - </li> - - <li><p><code>ORB::perform_work</code> and - <code>ORB::work_pending</code> are now implemented. - <code>ORB::work_pending</code> may need some additional work - in the future (since it currently always returns true).</p> - </li> - - <li><p>Provides dynamically linked wholesale assignment of ORB - strategies for communication, concurrency, demultiplexing, - scheduling, and dispatching using the ACE Service Configurator - framework.</p> - </li> - - <li><p>Supports several concurrency models out of the box: Reactive, - Thread-per-Connection, and ORB-per-thread. The ORB-per-thread - design is optimized for real-time I/O subsystems. (See: <A - HREF="../configurations.html">Configuration Guide</a>.)</p> - </li> - - <li><p>Supports <code>resolve_initial_references("<CORBA - Service>")</code> using ACE support for multicast. <em>(TAO - proprietary.)</em></p> - </li> - - <li><p>Support both native C++ exceptions and - <code>CORBA::Environment</code> based exceptions handling.</p> - - <li><p>Support for TAO proprietary <code>-ORBgioplite</code> - command-line option. When this option is enabled the ORB - removes a few fields of the GIOP messages that are normally not - used, such as the version numbers, the magic 'GIOP' string, the - service context, the Principal object, etc. This option give us - a slight performance improvement but it is important for - extremely low-latency systems (such as avionics), that - fortunately have tightly controlled environments so this kind of - optimization is safe to use.</p> - </li> - - <li><p>The buffers for outgoing CDR streams are allocated from TSS - memory pools, reducing locking on the critical path.</p> - </li> - - <li><p>Several optimizations on the critical path have been - implemented, carefully removing excesive locking, memory - allocations and data copying. In some cases special demarshaling - and marshaling functions where written for the request - headers.</p> - </li> - - <li><p>Adding a new option into TAO_Resource_Factory to control the - internal lock used by ORB's reacotr. With "<code>-ORBreactorlock - null</code>" added into <code>svc.conf</code>, you can eliminate - the token inside the Select_Reactor inside the ORB even on - multi-threaded platforms. This eliminate some overheads caused - by synchronizing access to the Select_Reactor. Usually, if you - have TSS ORB and are using reactive concurrency startegy, the - ORB are not accessed by multiple threads, then, you can safely - turn the lock off.</p> - </li> - - <li><p>Strategized the connection management scheme so that we don't - always have to pay the price of a look up in the connection - cache. Basically, we "hold" a service handler for a string of - requests.</p> - </li> - - <li><p>There is no need to call ORB::open if the port is 0. It will - automagically be called when the first stub is created.</p> - </li> - - <li><p>The ORB now handles nested upcalls correctly. See <a - href="../leader_follower.html">this </a>for details on the - design of the solution.</p> - </li> - - <li><p>Added optimization for collocated objects. This optimization - enables TAO to bypass communication layers and talks to - collocated objects directly.</p> - </li> - - <li><p>Making the collocation table configurable. We can either use - a global collocation table to share objects among ORBs, or use - the per-ORB collocation table.</p> - </li> - - <li><p>Implement the inheritance mechanism in - Default_Server_Connection_Handler to access the parent's - POA. This is necessary when we are using thread-per-connection - concurrency model.</p> - </li> - - <li><p>It is often desireable for a server to start up and not have - to specify the TCP port number on which the ORB will listen, - i.e., let the OS decide. While this works properly (by - providing an argument such as - `<code>-ORBendpoint iiop://localhost:0</code>'), the actual port - number used by the server won't be available after the server - starts listening. TAO now tries to bind the address when a port - set to zero is issued so it can get the actual address to publish - the IOR for clients' use.</p> - </li> - - <li><p>Broke the tight coupling between <code>CORBA_Object</code> - and <code>IIOP_Object</code> so that multiple - <code>CORBA_Object</code>s can share a single - <code>IIOP_Object</code>. This has a big win in - <code>_narrow</code> operations.</p> - </li> - - <li><p>The ORBs manipulation of object keys and object ids is now - consistent. Canonically, everything is managed as an opaque - sequence of octets. Conversion to/from strings is permitted, - with non-printables turning into a trigraph <b>\hl</b> where - <b>h</b> is the high nibble digit in hex, and <b>l</b> is the - low nibble in hex.</p> - </li> - - <li><p><code>CORBA_ORB::run()</code> should be able to be called - multiply in the same execution path now.</p> - </li> - - <li><p>Fixed the <b>LOCATION_FORWARD</b> capabilities to work as - described in the CORBA 2.1 and the POA specification.</p> - </li> - - <li><p>Support for <b><a - href="../Options.html#-ORBsndsock">-ORBsndsock</a></b> and <b><a - href="../Options.html#-ORBrcvsock">-ORBrcvsock</a></b> ORB - options. See <a href="../Options.html">options documentation</a> - for details.</p> - </li> - - <li><p>Support for connections pre-establishment using the <b><a - href="../Options.html#-ORBpreconnect">-ORBpreconnect</a></b> - option. This allows connections to be esablished before any - CORBA requests are made. See <a href="../Options.html">options - documentation</a> for details.</p> - </li> - - <li><p>Placed an optimization in IIOP::Profile that should speed up - invocations on the client side rather substantially. This was - done by caching an instance of <code>ACE_INET_Addr</code> in the - private portion of <code>Profile</code> because the cost of - constructing one for every invocation (in - <code>TAO_GIOP_Invocation::start</code>) was simply - enormous--the construction was something like 100 cycles on - Solaris. This is all because deep down this ends up calling - <code>gethostbyname()</code>, which can be very costly. Of - course, this is platform-dependent, so the improvements may not - be as great on a different platform.</p> - </li> - - <li><p>Eliminated need for <code>CORBA::Object</code> to keep a - pointer to its orb sitting around anywhere.</p> - </li> - - <li><p>Tested <code>CORBA_ORB::shutdown()</code> as a manner in - which a thread of control can request that - <code>CORBA_ORB::run()</code> should return and no longer - service requests. It only honors a <em>wait_for_completion</em> - argument of <b>FALSE</b> right now because we haven't fully - explored the issues which surround doing all the completion.</p> - </li> - - <li><p>Implemented <code>CORBA_ORB::shutdown()</code> as a manner in - which a thread of control can request that - <code>CORBA_ORB::run()</code> should return and no longer - service requests.</p> - </li> - - <li><p>Support for the -ORBInitRef option. This allows run-time - specification of an ObjectId:IOR mapping. It is used by - resolve_initial_references () and overrides the orb-install-time - defaults.</p> - </li> - - <li><p>minimal support for CORBA Contexts. This is an inherently - un-typesafe feature, and many believe it will disappear from - CORBA eventually, but in order to make _create_request() - compliant, we have added a CORBA_Context class. The only - permissible value for a Context pointer passed as an argument to - _create_request is 0. If a non-zero pointer is passed, a - NO_IMPLEMENT exception is raised.</p> - </li> - - <li><p>Support configuring TAO's component as both static and - dynamic services. Improve robustness of setting default - svc.conf entries. See <a - href="../configurations.html#programming">Configuration - Document</a> for details.</p> - </li> - - <li><p>TAO now understands <a - href="index.html#nservices">Interoperable Naming Service</a>'s - <code>iioploc://</code> and <code>iiopname://</code> - formats.</p> - </li> - - <li><p>Added Vendor ID and TAO-specific information to - the <code>CORBA_SystemException</code> minor status component. - The TAO-specific information currently consists of location - (in the TAO source code) and errno indications. See - <a href="../tao/corbafwd.h"><code>tao/corbafwd.h</code></a> - for values. <code>CORBA_SystemException::print_exception_tao_ ()</code> - should be used to print system exceptions. If a known (expected) - errno had been received, then it is printed. Otherwise, the low - 7 bits of the errno are printed (in decimal). They can be a bit - tricky to interpret, for example, because it might have been generated - on the server. We only maintain the low 7 bits because of size - restrictions on the minor status component.</p> - </li> - - <li><p>The <CODE>CORBA::ORB_init()</CODE> function returns the same - ORB if it is called twice with the same ORBid parameter or - if the "-ORBid value" option is present in the argv-list. - Please consult the CORBA specification for more details. - </p> - </li> - - <li><p>We implemented <CODE>GIOP 1.1</CODE>, including the support - for tagged components in IIOP profiles. - </p> - </li> - - <li><p>Added CORBA compliant collocated stubs implementation. The new - implementation now query POA for permission to proceed thus fixed - many potentially subtle problems. The original collocation implementation - is still supported using by specifying the -ORBCollocationStrategy direct - command option (because the original scheme has slightly less method - invocation overhead.) - </li> - -</ul> -<!-- --------------------- --> -<a href="#toc">Back to TOC</a> -<!-- --------------------- --> - -</BODY> -</HTML> diff --git a/TAO/docs/releasenotes/trader.html b/TAO/docs/releasenotes/trader.html deleted file mode 100644 index a8995ab1d81..00000000000 --- a/TAO/docs/releasenotes/trader.html +++ /dev/null @@ -1,1064 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - -<head> -<title>TAO Trading Service Documentation</title> -</head> - -<body text="#000000" link="#0000FF" vlink="#CC0000" bgcolor="#FFFFFF"> - -<hr> - -<h1 align="center">TAO Trading Service Documentation</h1> - -<hr> - -<p>The TAO transient Trading Service implements the COS TradingObject Service -specification, and conforms to the Linked Trader conformance criteria. This document -details how to use the TAO Trading Service from the following perspectives: - -<ul> - <li>as an importer bootstrapping to the Trading Service;</li> - <li>as a service offer exporter;</li> - <li>as an administrator;</li> - <li>as an out-of-the-box server process; </li> - <li>as a collocated object. </li> -</ul> - -<p>In addition, it covers running the Trading Service tests and discusses known bugs and -workarounds.</p> - -<p>This document assumes you are familiar with Trading Service concepts, such as -"importer," "exporter", "service type", "service -offer," and "dynamic property", as well as the roles of each of the Trading -Service's interfaces --- <tt>Lookup</tt>, <tt>Register</tt>, <tt>Admin</tt>, and <tt>Link</tt> -(the TAO implementation doesn't currently support <tt>Proxy</tt>). I recommend reading the -first two sections of the <a href="ftp://www.omg.org/pub/docs/formal/97-12-23.pdf">Trading -Service specification</a>. This document has the following layout: - -<ol> - <li><a href="#TheClientRole">The Client Role</a> <ul> - <li><a href="#BootstrappingtotheTradingService">Bootstrapping to the Trading Service</a> </li> - <li><a href="#The ImporterRolePerformingaQuery">The Importer Role --- Performing a Query</a><ul> - <li><a href="#Constraints">Constraints</a></li> - <li><a href="#Preferences">Preferences</a></li> - <li><a href="#Policies">Policies</a></li> - <li><a href="#FilteringProperties">Filtering Properties</a> </li> - <li><a href="#OfferIterators">Offer Iterators</a></li> - <li><a href="#PropertyEvaluation">Property Evaluation</a></li> - </ul> - </li> - <li><a href="#TheExporterRole">The Exporter Role --- Registering a Service Type and Offer</a> - <ul> - <li><a href="#TheServiceTypeRepository">The Service Type Repository</a> </li> - <li><a href="#ExportingWithdrawingandModifying">Exporting, Withdrawing, and Modifying - Service Offers</a> </li> - <li><a href="#ImplementingDynamicProperties">Implementing Dynamic Properties</a></li> - </ul> - </li> - <li><a href="#TheAdministratorRole">The Administrator Role --- Tweaking Policies and - Adjusting Links</a></li> - </ul> - </li> - <li><a href="#TheServerRole">The Server Role</a><ul> - <li><a href="#TheTAOTradingServiceApplication">The TAO <tt>Trading_Service</tt> Application</a></li> - <li><a href="#ColocatingtheTradingServiceinaTAOApplication">Colocating the Trading Service - in a TAO Application</a></li> - </ul> - </li> - <li><a href="#RunningtheTradingServiceTests">Running the Trading Service Tests</a></li> - <li><a href="#KnownBugsandWorkarounds">Known Bugs and Workarounds</a></li> - <li><a href="#FutureWork">Future Work</a></li> -</ol> - -<hr> - -<h1><a name="TheClientRole">The Client Role</a></h1> - -<p align="left">There are three categories of operations that a client can perform on a -Trading Service instance: exporting a service offer to the Trading Service, importing a -list of Service Offers whose properties satisfy a constraint expression, and attending to -administrative duties --- tweaking policies or adjusting links. The first order of -business, of course, is obtaining a reference to a Trading Service instance, assuming that -instance is not colocated with the client. </p> - -<h2 align="left"><a name="BootstrappingtotheTradingService">Bootstrapping to the Trading -Service</a></h2> - -<p align="left">Like with the Naming Service, the ORB will obtain a reference to a Trading -Service instance's <tt>Lookup</tt> interface when a client invokes the <tt>CORBA::ORB::resolve_initial_references</tt> -method and passes to it the <tt>ObjectID</tt> "<tt>TradingService</tt>". The -following TAO code bootstraps to the Trading Service:</p> - -<table border="1" width="100%" cellpadding="6"> - <tr> - <td width="100%"><pre>TAO_TRY -{ - TAO_ORB_Manager orb_manager; - orb_manager.init (argc, argv, TAO_TRY_ENV); - TAO_CHECK_ENV; - CORBA::ORB_var orb = orb_manager.orb (); - CORBA::Object_var trading_obj = - orb->resolve_initial_references ("TradingService"); - CosTrading::Lookup_var lookup_if = - CosTrading::Lookup::_narrow (trading_obj.in (), TAO_TRY_ENV); - TAO_CHECK_ENV; -} -TAO_CATCHANY -{ - TAO_TRY_ENV.print_exception ("Failed to bootstrap to a trader"); -} -TAO_ENDTRY;</pre> - </td> - </tr> -</table> - -<p>The first time <tt>resolve_initial_references</tt> is called, the ORB uses a multicast -protocol to locate an existing trader. The ORB emits a multicast packet containing a field -identifying the desired service --- Naming or Trading --- and the port number that the -client is listening on for the response (the IP address can be inferred from the packet). -When the trader receives the packet and finds that the id contained within matches its -own, it opens a socket to the client on the designated port, and sends its IOR, which the -ORB converts to an object reference that it caches. </p> - -<p>If the trader IOR is known ahead of time, the string can be passed to the client in the -environment variable <tt>TradingService</tt>, or by the command line option <tt>-ORBtradingserviceior -<IOR></tt>. Likewise, if the multicast port is known ahead of time and differs from -the default port, the port number can be passed to the client in the environment variable <tt>TradingServicePort</tt>, -or by the command line option <tt>-ORBtradingserviceport <PORTNUM></tt>. </p> - -<h2><a name="The ImporterRolePerformingaQuery">The Importer Role --- Performing a Query</a></h2> - -<p>Once the importer has obtained a reference to a trader's <tt>Lookup</tt> interface, it -next needs to fire up a query. The query method takes nine parameters (aside from the <tt>CORBA::Environment</tt>):</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="39%"><tt>const CosTrading::ServiceTypeName</tt></td> - <td width="61%">The Trading Service will search Offers belonging to this subtype. If the <tt>exact_type_match</tt> - policy wasn't explicitly set to false, then offers belonging to subtypes of this type will - also be searched. </td> - </tr> - <tr> - <td width="39%"><tt>const CosTrading::Constraint</tt></td> - <td width="61%">An expression in the OMG standard constraint language, where each property - name is a property defined in the Service Type description of the type being searched.</td> - </tr> - <tr> - <td width="39%"><tt>const CosTrading::Lookup::Preference</tt></td> - <td width="61%">An expression in the OMG standard constraint language dictating how offers - in the <tt>returned_offers</tt> sequence should be ordered.</td> - </tr> - <tr> - <td width="39%"><tt>const CosTrading::PolicySeq</tt></td> - <td width="61%">Policies governing the breadth of search and the type of permissible - offers. A policy is a name/value pair --- a string and an <tt>Any</tt> --- that affect the - search algorithm. </td> - </tr> - <tr> - <td width="39%"><tt>const CosTrading::Lookup::SpecifiedProps</tt></td> - <td width="61%">A union specifying which properties should be returned in each offer. If - the descriminator is <tt>CosTrading::Lookup::some</tt>, the union contains the list - of designated property names. Other options are <tt>all</tt>or <tt>none</tt>. </td> - </tr> - <tr> - <td width="39%"><tt>CORBA::ULong how_many</tt></td> - <td width="61%">The number of offers that should be placed in the returned sequence.</td> - </tr> - <tr> - <td width="39%"><tt>CosTrading::OfferSeq_out</tt></td> - <td width="61%">A list of ordered offers whose properties meet the constraints.</td> - </tr> - <tr> - <td width="39%"><tt>CosTrading::OfferIterator_out</tt></td> - <td width="61%">Iterator over returned offers in excess of how_many --- unordered.</td> - </tr> - <tr> - <td width="39%"><tt>CosTrading::PolicyNameSeq_out</tt></td> - <td width="61%">A sequence of policy names for policies that limited the search.</td> - </tr> -</table> - -<h3><a name="Constraints">Constraints</a></h3> - -<p>A constraint is a string in the OMG standard constraint language (the BNF can be found -at the end of the specification). The trader iterates over applicable offers, and for each -offer determines if its properties meet the constraints, replacing property names in the -string with their values and computing the result. If the constraint evaluates to true, -the offer is placed in the pool of matched offers. If the constraint string is -syntactically invalid, contains property names not found in the service type description -for the listed service type, or has operators with mismatched operand types, the query -method will throw an <tt>InvalidConstraint</tt> exception. </p> - -<p>Operands can be of two types: property names or literals. A property name is an -unquoted string of alphanumeric characters and underscores that begins with a letter. The -service type describes the type of a property. A literal is an signed or unsigned integer, -floating point number --- scientific notation acceptable ---, single-quoted string, or -boolean --- written TRUE or FALSE. </p> - -<p>The constraint language supports the following operations:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="25%">Arithmetic (+, -, *, /)</td> - <td width="34%"><tt>Disk_Space*1000 - Amount_Used/10</tt></td> - <td width="41%">Accepts two numeric operands.</td> - </tr> - <tr> - <td width="25%">Inequality (<,>,<=,>=)</td> - <td width="34%"><tt>Amount_Used < Disk_Space</tt></td> - <td width="41%">Accepts two numeric or two string operands.</td> - </tr> - <tr> - <td width="25%">Equality (==, !=)</td> - <td width="34%"><tt>Amount_Used == Disk_Space</tt></td> - <td width="41%">Accepts two numeric, two string, or two boolean operands.</td> - </tr> - <tr> - <td width="25%">Substring (~)</td> - <td width="34%"><tt>'.wustl.edu' ~ Domain_Name</tt></td> - <td width="41%">Accept two string operands. Returns true if the right string contains the - left.</td> - </tr> - <tr> - <td width="25%">Sequence inclusion (in)</td> - <td width="34%"><tt>'sbw1' in User_Queue</tt></td> - <td width="41%">Accepts an operand of a primitive CORBA type on the left, and a sequence - of the same type on the right. Returns true when the sequence contains the value in the - left operand, false otherwise.</td> - </tr> - <tr> - <td width="25%">Property existence (exist)</td> - <td width="34%"><tt>exist User_Queue</tt></td> - <td width="41%">Accepts a property name. Returns true if the property is defined in the - offer.</td> - </tr> -</table> - -<h3><a name="Preferences">Preferences</a></h3> - -<p>A preference is a constraint language string that determines the order of offers in the -returned offer sequence. There are five types of preferences:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="18%"><tt>min</tt> <expression></td> - <td width="82%">Offers are ordered by ascending expression value. The expression must - return a number.</td> - </tr> - <tr> - <td width="18%"><tt>max</tt> <expression> </td> - <td width="82%">Offers are ordered by descending expression value. The expression must - return a number. </td> - </tr> - <tr> - <td width="18%"><tt>with</tt> <expression></td> - <td width="82%">Offers are partitioned into two parts: those offers for which the - expression returns true are placed in the front, the rest in the back. The expression must - return a boolean value.</td> - </tr> - <tr> - <td width="18%"><tt>random</tt></td> - <td width="82%">Offers in the sequence are shuffled.</td> - </tr> - <tr> - <td width="18%"><tt>first</tt></td> - <td width="82%">Offers are placed in the sequence in the order they're evaluated.</td> - </tr> -</table> - -<h3><a name="Policies">Policies</a></h3> - -<p>The following import policies are descibed in the specification and supported by the -TAO Trading Service:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="22%"><tt>exact_type_match</tt></td> - <td width="18%"><tt>CORBA::Boolean</tt></td> - <td width="60%">True --- Search only considers offers belonging to the given type.<br> - False --- Search considers offers belonging to the given type or any of its subtypes.</td> - </tr> - <tr> - <td width="22%"><tt>search_card</tt></td> - <td width="18%"><tt>CORBA::ULong</tt></td> - <td width="60%">Search ceases after <tt>search_card</tt> number of offers have been - evaluated.</td> - </tr> - <tr> - <td width="22%"><tt>match_card</tt></td> - <td width="18%"><tt>CORBA::ULong</tt></td> - <td width="60%">Search ceases after <tt>search_card</tt> number of offers have been - matched.</td> - </tr> - <tr> - <td width="22%"><tt>return_card</tt></td> - <td width="18%"><tt>CORBA::ULong</tt></td> - <td width="60%">Query returns at most <tt>return_card</tt> number of offers.</td> - </tr> - <tr> - <td width="22%"><tt>support_dynamic_properties</tt></td> - <td width="18%"><tt>CORBA::Boolean</tt></td> - <td width="60%">Search considers offers with dynamic properties.</td> - </tr> - <tr> - <td width="22%"><tt>support_modifiable_properties</tt></td> - <td width="18%"><tt>CORBA::Boolean</tt></td> - <td width="60%">Search considers offers with not readonly properties.</td> - </tr> - <tr> - <td width="22%"><tt>starting_trader</tt></td> - <td width="18%"><tt>CosTrading::TraderName</tt></td> - <td width="60%">Query is forwarded across all links in the policy, and search begins at - the final trader.</td> - </tr> - <tr> - <td width="22%"><tt>hop_count</tt></td> - <td width="18%"><tt>CORBA::ULong</tt></td> - <td width="60%">Maximum depth a query should be propagated in the trader federation.</td> - </tr> - <tr> - <td width="22%"><tt>link_follow_rule</tt></td> - <td width="18%"><tt>CosTrading::FollowOption</tt></td> - <td width="60%">Query propagates to other traders if the <tt>link_follow_rule</tt> permits - it.</td> - </tr> -</table> - -<p>The TAO Trading Service comes with a handy utility --- <tt>TAO_Policy_Manager</tt> --- -for creating a policy sequence to pass to the query method that won't incur any -exceptions. Use the <tt>TAO_Policy_Manager</tt> in the following way:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>TAO_Policy_Manager policies; -policies.exact_type_match (CORBA::B_FALSE); -policies.search_card (16*NUM_OFFERS); -policies.match_card (16*NUM_OFFERS); -policies.return_card (16*NUM_OFFERS); -policies.link_follow_rule (CosTrading::local_only); -const CosTrading::PolicySeq& policy_seq = policies.policy_seq ();</pre> - </td> - </tr> -</table> - -<h3><a name="FilteringProperties">Filtering Properties</a></h3> - -<p>If the client wants only a subset of the properties defined for a service type returned -in matching offers, it can specify those property names in the <tt>desired_properties</tt> -parameter of the query method. Pass the <tt>prop_names</tt> method of <tt>CosTrading::Lookup::SpecifiedProperties</tt> -a <tt>CosTrading::PropNameSeq</tt>:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>char* props[] = {"Name", "Description", "Location", "Host_Name" }; -CosTrading::Lookup::SpecifiedProps desired_props; -CosTrading::PropertyNameSeq prop_name_seq (4, 4, props, CORBA::B_FALSE); -desired_props.prop_names (prop_name_seq);</pre> - </td> - </tr> -</table> - -<h3><a name="OfferIterators">Offer Iterators</a></h3> - -<p>Those offers returned from the query in excess of <tt>how_many</tt> are placed in an -offer iterator for deferred retrieval. The <tt>CosTrading::OfferIterator::next_n</tt> -method will allocate a sequence and fill it with either n offers, or if it has fewer than <tt>n</tt> -offers, the remaining offers. The <tt>next_n</tt> method returns true if the iterator -contains more offers, and false if it's been depleted. After finishing with the iterator, -invoke its <tt>destroy</tt> method to release any server-side resources.</p> - -<p>The following code is an example of obtaining offers from a <tt>CosTrading::OfferIterator</tt>:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>CORBA::Boolean any_left = CORBA::B_FALSE; -CORBA::Environment _env;</pre> - <pre>do - { - CosTrading::OfferSeq_ptr iter_offers_ptr; - CosTrading::OfferSeq_out iter_offers_out (iter_offers_ptr); - - any_left = offer_iterator->next_n (length, - iter_offers_out, - _env); - TAO_CHECK_ENV_RETURN (_env, 0); - - CosTrading::OfferSeq_var iter_offers (iter_offers_ptr); - // Process offers... - - } while (any_left);</pre> - </td> - </tr> -</table> - -<h3><a name="PropertyEvaluation">Property Evaluation</a></h3> - -<p>After the client completes a query that used dynamic properties, to review the property -values of the returned offers, it has to distinguish between <tt>Anys</tt> containing -static properties and <tt>Anys</tt> containing dynamic property structures. The <tt>TAO_Property_Evaluator</tt> -class is a handy utility to obtain property values that hides how it evalutes properties -for the client --- by simple <tt>Any</tt> value extraction for static properties, or by -calling back to a dynamic property interface. The <tt>TAO_Property_Evaluator</tt> caches -the value of a dynamic property, and frees the allocated <tt>Anys</tt> during its -destruction. </p> - -<p>The following code demonstrates how to use the <tt>TAO_Property_Evaluator</tt> to dump -the properties of an offer to the screen. </p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>TAO_Property_Evaluator prop_eval (prop_seq); -for (int length = prop_seq.length (), k = 0; k < length; k++) - { - ACE_DEBUG ((LM_DEBUG, "%-15s: ", prop_seq[k].name.in ())); - TAO_TRY - { - CORBA::Boolean is_dynamic = prop_eval.is_dynamic_property (k); - TAO_CHECK_ENV; - - value = prop_eval.property_value(k, env); - TAO_CHECK_ENV; - - if (value != 0) - CORBA::Any::dump (*value); - } - TAO_CATCHANY - { - ACE_DEBUG ((LM_DEBUG, "Error retrieving property value.\n")); - } - TAO_ENDTRY; - }</pre> - </td> - </tr> -</table> - -<h2><a name="TheExporterRole">The Exporter Role --- Registering a Service Type and Offer</a></h2> - -<p>Before an exporting client can register a new service offer with the Trading Service, -it needs to ensure first that its service type is present in the service type repository -of the target trader. The most efficient way to do this is to first invoke the <tt>export</tt> -method on the <tt>Register</tt> interface, and if it raises an <tt>UnknownServiceType</tt> -exception, obtain a reference to the Repository, add the Service Type, and attempt the <tt>export</tt> -a second time. Here's the boilerplate code:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>CORBA::Object_var trading_obj = - orb_ptr->resolve_initial_references ("TradingService"); -CosTrading::Lookup_var lookup_if = - CosTrading::Lookup::_narrow (trading_obj.in (), _env); -TAO_CHECK_ENV_RETURN (_env, -1); -CosTrading::Register_var register_if = lookup_if->register_if (_env); -TAO_CHECK_ENV_RETURN (_env, -1); -CosTrading::TypeRepository_ptr obj = this->trader_->type_repos (_env); -CosTradingRepos::ServiceTypeRepository_var str = - CosTradingRepos::ServiceTypeRepository::_narrow (obj, _env); -TAO_CHECK_ENV_RETURN (_env, -1); - -TAO_TRY - { - // Attempt to export the offer. - offer_id = - register_id->export (object_ref, type, props, TAO_TRY_ENV); - TAO_CHECK_ENV; - } -TAO_CATCH (CosTrading::UnknownServiceType, excp) - { - // If the ServiceTypeName wasn't found, we'll have to add the - // type to the Service Type repository ourselves. - str->add_type (type, - object_ref->_interface_repository_id (), - prop_struct_seq, - super_type_name_seq, - _env); - TAO_CHECK_ENV_RETURN (_env, 0); - - // Now we'll try again to register the offer. - offer_id = reg->export (object_ref, type, this->tprops_, _env); - TAO_CHECK_ENV_RETURN (_env, 0); - - TAO_TRY_ENV.clear (); - } -TAO_CATCHANY - { - // Sigh, all our efforts were for naught. - TAO_RETHROW_RETURN (0); - } -TAO_ENDTRY;</pre> - </td> - </tr> -</table> - -<h3><a name="TheServiceTypeRepository">The Service Type Repository</a></h3> - -<p>Creating a service type description is simply a matter of filling in two sequences: a <tt>CosTradingRepos::ServiceTypeRepository::PropStructSeq</tt> -and a <tt>CosTradingRepos::ServiceTypeRepository::ServiceTypeNameSeq</tt>. When filling in -the <tt>value_type</tt> field, remember to up the reference count of the <tt>TypeCode</tt>, -since otherwise the <tt>TypeCode_var</tt> will sieze control of the memory and free it. -Here's a code excerpt taken from <tt>export_test</tt> showing how to build the first -couple elements of such sequences:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>this->type_structs_[TT_Info::PLOTTER].props.length (2); -this->type_structs_[TT_Info::PLOTTER].super_types.length (1); -this->type_structs_[TT_Info::PLOTTER].super_types[0] = -TT_Info::INTERFACE_NAMES[TT_Info::REMOTE_IO]; -this->type_structs_[TT_Info::PLOTTER].props[0].name = -TT_Info::PLOTTER_PROPERTY_NAMES[TT_Info::PLOTTER_NUM_COLORS]; -this->type_structs_[TT_Info::PLOTTER].props[0].value_type = -CORBA::TypeCode::_duplicate (CORBA::_tc_long); -this->type_structs_[TT_Info::PLOTTER].props[0].mode = -CosTradingRepos::ServiceTypeRepository::PROP_NORMAL; -this->type_structs_[TT_Info::PLOTTER].props[1].name = -TT_Info::PLOTTER_PROPERTY_NAMES[TT_Info::PLOTTER_AUTO_LOADING]; -this->type_structs_[TT_Info::PLOTTER].props[1].value_type = -CORBA::TypeCode::_duplicate (CORBA::_tc_boolean); -this->type_structs_[TT_Info::PLOTTER].props[1].mode = -CosTradingRepos::ServiceTypeRepository::PROP_READONLY;</pre> - </td> - </tr> -</table> - -<h3><a name="ExportingWithdrawingandModifying">Exporting, Withdrawing, and Modifying -Service Offers</a></h3> - -<p>Like with adding a Service Type, exporting an offer is just filling in the sequences. -For offers, of course, property values are passed, so this involves employing the <tt>Any</tt> -insertion operators. Here's a code exerpt from <tt>export_test</tt>:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>CosTrading::PropertySeq prop_seq (2); -prop_seq[0].name = - TT_Info::PLOTTER_PROPERTY_NAMES[TT_Info::PLOTTER_NUM_COLORS]; -prop_seq[0].value <<= ACE_static_cast (CORBA::Long, 256); -prop_seq[1].name = - TT_Info::PLOTTER_PROPERTY_NAMES[TT_Info::PLOTTER_AUTO_LOADING]; -prop_seq[1].value <<= CORBA::Any::from_boolean (CORBA::B_TRUE);</pre> - </td> - </tr> -</table> - -<p>The <tt>export_test</tt> returns a <tt>CosTrading::OfferId</tt> string, which is -required to perform the <tt>withdraw</tt> and <tt>modify</tt> operations on the exported -offer. <tt>withdraw</tt> requires that you simply pass the <tt>OfferId</tt> of the offer -to be withdrawn, while <tt>modify</tt> takes two additional sequences: a <tt>CosTrading::PropertyNameSeq</tt> -of property names to be removed from the offer, and a <tt>CosTrading::PropertySeq</tt> of -offers to be added or changed in the offer. </p> - -<h3><a name="ImplementingDynamicProperties">Implementing Dynamic Properties</a></h3> - -<p>To export an offer with a dynamic property: - -<ul> - <li>inherit from the <tt>TAO_Dynamic_Property</tt> class and implement its <tt>DP_Eval</tt> - method; </li> - <li>create a <tt>CosTradingDynamic::DynamicProperty</tt> structure using the <tt>TAO_Dynamic_Property::construct_dynamic_prop</tt> - method; </li> - <li>insert the <tt>CosTradingDynamic::DynamicProperty</tt> in the value field of the - property. </li> -</ul> - -<p>The following code, taken from the <tt>export_test</tt> example, illustrates this:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>// Step 1: Write the Dynamic Property callback handler. -class Simple_DP : public TAO_Dynamic_Property -{ -public: - - virtual CORBA::Any* evalDP (const char* name, - CORBA::TypeCode_ptr returned_type, - const CORBA::Any& extra_info, - CORBA::Environment& _env) - TAO_THROW_SPEC ((CosTradingDynamic::DPEvalFailure)); -}; - -CORBA::Any* -Simple_DP::evalDP (const char* name, - CORBA::TypeCode_ptr returned_type, - const CORBA::Any& extra_info, - CORBA::Environment& _env) - TAO_THROW_SPEC ((CosTradingDynamic::DPEvalFailure)) -{ - CORBA::Any* return_value = 0; - ACE_NEW_RETURN (return_value, CORBA::Any, 0); - - (*return_value) <<= ACE_static_cast (CORBA::ULong, ACE_OS::rand ()); - return return_value; -}</pre> - <pre>// Step 2: Create the Dynamic Property -Simple_DP dp; -CORBA::Any extra_info; -CosTrading::PropertySeq prop_seq (1); -CosTrading::DynamicProp* dp_struct = - dp.construct_dynamic_prop ("prop_name", - CORBA::_tc_ulong, - extra_info);</pre> - <pre>// Step 3: Turn over the dynamic property to the propery value Any. -CORBA::Environment env; -prop_seq[0].name = "prop_name"; -prop_seq[0].value.replace (CosTrading::_tc_DynamicProp, - dp_struct, - CORBA::B_TRUE, - env); -TAO_CHECK_ENV_RETURN (env, -1);</pre> - </td> - </tr> -</table> - -<h2><a name="TheAdministratorRole">The Administrator Role --- Tweaking Policies and -Adjusting Links</a></h2> - -<p>The trader can be configured remotely through two interfaces: the <tt>Admin</tt> -interface, for tweaking global policies, enabling and disabling interfaces, and dumping -the trader contents; and the <tt>Link</tt> interface, for attaching to and detaching from -other traders. </p> - -<p>Adjusting policies is straightforward. Here's an example of setting the <tt>max_search_card</tt> -policy:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>// lookup_if returned from resolve_initial_references. -CosTrading::Admin_var admin_if = - lookup_if->admin_if (TAO_TRY_ENV); -TAO_CHECK_ENV;</pre> - <pre>admin_if->set_max_match_card (200);</pre> - </td> - </tr> -</table> - -<p>Here's an example of using the list_offers method on the Admin interface to remove all -offers from the Trader:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>TAO_TRY -{ -CosTrading::OfferIdIterator_ptr offer_id_iter; -CosTrading::OfferIdSeq_ptr offer_id_seq; - -// lookup_if returned from resolve_initial_references. -CosTrading::Admin_var admin_if = - lookup_if->admin_if (TAO_TRY_ENV); -TAO_CHECK_ENV; - -CosTrading::Register_var register_if = - lookup_if->register_if (TAO_TRY_ENV); -TAO_CHECK_ENV; - -admin_if->list_offers (10, - CosTrading::OfferIdSeq_out (offer_id_seq), - CosTrading::OfferIdIterator_out (offer_id_iter), - TAO_TRY_ENV); -TAO_CHECK_ENV; - -if (offer_id_seq != 0) - { - CosTrading::OfferIdSeq_var offer_id_seq_var (offer_id_seq); - for (CORBA::ULong i = 0; i < offer_id_seq_var.length (); i++) - { - register_if->withdraw (offer_id_seq_var[i], TAO_TRY_ENV); - TAO_CHECK_ENV; - } - } - -if (offer_id_iter != CosTrading::OfferIdIterator::_nil ()) - { - CORBA::Boolean any_left = CORBA::B_FALSE; - CosTrading::OfferIdSeq_ptr id_seq = 0; - CosTrading::OfferIdIterator_var offer_id_iter_var (offer_id_iter); - - do - { - any_left = - offer_id_iter->next_n (length, - CosTrading::OfferIdSeq_out (id_seq), - TAO_TRY_ENV); - TAO_CHECK_ENV; - - CORBA::ULong offers = id_seq->length (); - for (CORBA::ULong i = 0; i < offers; i++) - { - register_if->withdraw (id_seq[i], TAO_TRY_ENV); - TAO_CHECK_ENV; - } - - delete id_seq; - } - while (any_left); - - offer_id_iter->destroy (TAO_TRY_ENV); - TAO_CHECK_ENV; - } -} -TAO_CATCHANY -{ - // Handle Errors. -} -TAO_ENDTRY;</pre> - </td> - </tr> -</table> - -<p>Here's an example a trader linking itself to another trader (<tt>this->trader_</tt> -is a colocated trader --- see the next section for more information): </p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>TAO_TRY - { - CosTrading::Link_var link_if = lookup_if->link_if (TAO_TRY_ENV); - TAO_CHECK_ENV; - - TAO_Trading_Components_Impl& trd_comp = - this->trader_->trading_components (); - CosTrading::Lookup_ptr our_lookup = trd_comp.lookup_if (); - CosTrading::Link_ptr our_link = trd_comp.link_if (); - - link_if->add_link (this->name_.in (), - our_lookup, - CosTrading::always, - CosTrading::always, - TAO_TRY_ENV); - TAO_CHECK_ENV; - - our_link->add_link ("Bootstrap_Trader", - lookup_if.in (), - CosTrading::always, - CosTrading::always, - TAO_TRY_ENV); - } -TAO_CATCHANY -{ - // Handle Errors. -} -TAO_ENDTRY;</pre> - </td> - </tr> -</table> - -<hr> - -<h1><a name="TheServerRole">The Server Role</a></h1> - -<p>The TAO Trading Service comes with an out-of-the-box executable suitable for common -use. However, it can also easily be colocated with any other TAO server to add Trading -Service functionality to that server.</p> - -<h2><a name="TheTAOTradingServiceApplication">The TAO Trading Service Application</a></h2> - -<p>This out-of-the-box server takes a number of command line arguments:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="26%"><tt>-TSthreadsafe</tt></td> - <td width="74%">The Trader will use reader/writer locks to protect the offer database and - link collection, and normal thread mutexes for the rest of the shared state --- global - policies, support attributes, and interface accessors. (default is not thread safe; Null - Mutexes are used)</td> - </tr> - <tr> - <td width="26%"><tt>-TSconformance</tt></td> - <td width="74%">Determines which conformance category the Trading Service will meet:<br> - <table border="0" width="100%" cellpadding="3"> - <tr> - <td width="18%"><ul> - <li><em>query</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Instantiates the <tt>Lookup</tt> interface only</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>simple</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Instantiates the <tt>Lookup</tt> and <tt>Register</tt> - interfaces</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>standalone</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Instantiates the <tt>Lookup</tt>, <tt>Register</tt>, - and <tt>Admin</tt> interfaces</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>linked</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Instantiates the <tt>Lookup</tt>, <tt>Register</tt>, - <tt>Admin</tt>, and <tt>Link</tt> interfaces (default)</td> - </tr> - </table> - </td> - </tr> - <tr> - <td width="26%"><tt>-TSsupports_dynamic_properties</tt></td> - <td width="74%"><table border="0" width="100%" cellpadding="3"> - <tr> - <td width="18%"><ul> - <li><em>true</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Will consider offers with dynamic properties in - queries unless explicitly disabled by a policy passed to the query method. (default)</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>false</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Will not consider offers with dynamic properties - in queries, unless explicitly enabled by a policy passed to the query method.</td> - </tr> - </table> - </td> - </tr> - <tr> - <td width="26%"><tt>-TSsupports_modifiable_properties</tt></td> - <td width="74%"><table border="0" width="100%" cellpadding="3"> - <tr> - <td width="18%"><ul> - <li><em>true</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Will consider offers with not explicitly - modifable properties in queries unless explicitly disabled by a policy passed to the query - method. Enables the <tt>modify</tt> method on the <tt>Register</tt> interface. (default)</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>false</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">Will not consider dynamic properties in queries, - unless explicitly overridden by a query policy. Diables <tt>modify</tt> method on the <tt>Register</tt> - interface.</td> - </tr> - </table> - </td> - </tr> - <tr> - <td width="26%"><tt>-TSdef_search_card</tt></td> - <td width="74%">Search cardinality if none is specified as a query policy. (default is - 200)</td> - </tr> - <tr> - <td width="26%"><tt>-TSmax_search_card</tt></td> - <td width="74%">Upper limit on the search cardinality for a query. (default is 500)</td> - </tr> - <tr> - <td width="26%"><tt>-TSdef_match_card</tt></td> - <td width="74%">Match cardinality if none is specified as a query policy. (default is 200)</td> - </tr> - <tr> - <td width="26%"><tt>-TSmax_match_card</tt></td> - <td width="74%">Upper limit on the match cardinality for a query. (default is 500)</td> - </tr> - <tr> - <td width="26%"><tt>-TSdef_return_card</tt></td> - <td width="74%">Return cardinality if none is specified as a query policy. (default is - 200)</td> - </tr> - <tr> - <td width="26%"><tt>-TSmax_return_card</tt></td> - <td width="74%">Upper limit on the return cardinality for a query. (default is 500)</td> - </tr> - <tr> - <td width="26%"><tt>-TSdef_hop_count</tt></td> - <td width="74%">The depths a federated query may go if no query policy is specified. - (default 5)</td> - </tr> - <tr> - <td width="26%"><tt>-TSmax_hop_count</tt></td> - <td width="74%">The maximum number of links a federated query can travel after it passes - through this trader. (default is 10) </td> - </tr> - <tr> - <td width="26%"><tt>-TSdef_follow_policy</tt></td> - <td width="74%"><table border="0" width="100%" cellpadding="3"> - <tr> - <td width="18%"><ul> - <li><em>always</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader will always pass a query onto the - next available linked trader.</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>if_no_local</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader will pass a query onto the next - trader only if the local search produced no results. (default)</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>local_only</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader will never pass on a query.</td> - </tr> - </table> - </td> - </tr> - <tr> - <td width="26%"><tt>-TSmax_follow_policy</tt></td> - <td width="74%"><table border="0" width="100%" cellpadding="3"> - <tr> - <td width="18%"><ul> - <li><em>always</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader doesn't limit the importer to the - local offer space. (default)</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>if_no_local</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader refuses to pass on queries of the - local search matched offers.</td> - </tr> - <tr> - <td width="18%"><ul> - <li><em>local_only</em></li> - </ul> - </td> - <td width="82%" valign="top" align="left">The trader will never allow federated queries.</td> - </tr> - </table> - </td> - </tr> - <tr> - <td width="26%"><tt>-ORBtradingserviceport</tt></td> - <td width="74%">Port on which to listen for multicast bootstrap requests.</td> - </tr> - <tr> - <td width="26%"><tt>-ORBtradingserviceport</tt></td> - <td width="74%">Port on which to listen for multicast bootstrap requests.</td> - </tr> - <tr> - <td width="26%"><tt>-TSdumpior</tt></td> - <td width="74%">Dumps the trader's IOR to a file (default is stdout).</td> - </tr> -</table> - -<p>By default the trader will listen for multicast <tt>resolve_initial_references</tt> -requests, and respond with the IOR of its <tt>Lookup</tt> inteface. For the purposes of -testing federated queries, when passed the <tt>-TSfederate</tt> method, instead of -becoming a bootstrappable server, the <tt>Trading_Service</tt> application will bootstrap -itself to a multicast trader, link itself to that trader and every other trader accessible -through that trader. This protocol will have all traders on the multicast network form a -complete graph. </p> - -<h2><a name="ColocatingtheTradingServiceinaTAOApplication">Colocating the Trading Service -in a TAO Application</a></h2> - -<p>Colocating the Trading Service in a TAO application amounts to constructing a <tt>TAO_TRADER</tt> -object using the <tt>TAO_Trader_Factory::construct_trader</tt> call. The <tt>argc</tt> and -<tt>argv</tt> parameters to <tt>construct_trader</tt> contain the configuration parameters -described in the previous section. The trader is also configurable programatically through -its attribute classes. The follow code exerpt demonstrates this. </p> - -<p>In addition the application will need to create a service type repository -implementation --- TAO's being the <tt>TAO_Service_Type_Repository</tt> --- and configure -the trader with it. The service type repository is separate from the trader in this way to -allow, for example, multiple traders to share the same service type repository. The -following code exerpt also demontrates configuring the repository:</p> - -<table border="1" width="100%" cellpadding="3"> - <tr> - <td width="100%"><pre>TAO_TRADER* trader = TAO_Trader_Factory::create_trader (argc, argv); -TAO_Support_Attributes_Impl& sup_attr = trader->support_attributes (); -TAO_Import_Attributes_Impl& imp_attr = trader->trading_components (); - -// Configure the trader with a service type repository. -CORBA::Environment _env; -TAO_Service_Type_Repository type_repos* type_repos = 0; -ACE_NEW (type_repos, TAO_Service_Type_Repository); -sup_attr.type_repos (type_repos->_this (_env)); -TAO_CHECK_ENV_RETURN (_env, -1);</pre> - <pre>// Configure other policies, overriding the command line arguments. -imp_attr.search_card (20); -sup_attr.supports_dynamic_properties (CORBA::B_FALSE);</pre> - </td> - </tr> -</table> - -<p>The trader interfaces register themselves with the default POA during the Trading -Service's construction. All that remains is to activate the POA and enter the ORB event -loop. </p> - -<hr> - -<h1><a name="RunningtheTradingServiceTests">Running the Trading Service Tests</a></h1> - -<p>There are two executables that test the Trading Service funtionality --- one to test -the exporter role, and the other, the importer role. To run the tests simply launch the <tt>Trading_Service</tt> -application, then run the <tt>export_test</tt> executable found in the <tt>orbsvcs/tests/Trading</tt> -directory. When the <tt>export_test</tt> ceases to output data and enters the event loop, -run the <tt>import_test</tt> found in the same directory. </p> - -<p>Also of importance: the <tt>-TSdumpior filename </tt> argument to the trader dumps -its IOR to the file. You can then paste the contents on the command line to -the tests with <tt>-ORBtradingserviceior IOR</tt>, or into the environment variable -<tt>TradingServiceIOR</tt>.</p> - -<p>The expected output of the tests can be found in the README file in the -tests directory.</p> - -<p>To test federated queries, run at least three copies of the <tt>Trading_Service</tt> -application, each using the <tt>-TSfederate</tt> flag. The traders will form a complete -graph, with each link follow policy set to <tt>CosTrading::always</tt>. When run with the <tt>-f</tt> -flag, the <tt>export_test</tt> will add the service types and export offers to each of the -traders in the federation. When run with the <tt>-f</tt> flag, the <tt>import_test </tt>will -perform a directed query to a trader two links distant from the trader boostrapped to, in -addition to performing federated queries. </p> - -<p>By default the tests dump the contents of service types and offers to the screen so the -tester can validate the results. To run the tests in quiet mode, where the results of the -describe and query methods are concealed, use the <tt>-q</tt> flag.</p> - -<hr> - -<h1><a name="KnownBugsandWorkarounds">Known Bugs and Workarounds</a></h1> - - <p>At this point there are no known problems with TAO that affect the - Trading service.</p> - -<hr> - -<h1><a name="FutureWork">Future Work</a></h1> - -<ul> - <li><strong>Persistence</strong> --- Have the Trading Service offer database and service - type repository survive the lifetime of a single Trading Service process. This would be - accomplished by either taking advantage of the ability to serialize IDL types --- using - CDR streams --- or through memory-mapped files, <em>a la </em>the ACE Naming Service.</li> -</ul> - -<ul> - <li><strong>The <tt>Proxy</tt> Interface </strong>--- Should we ever feel so motivated, we - might implement the <tt>Proxy</tt> interface. </li> -</ul> - -<hr> - -<address> - <a href="mailto:sbw1@cs.wustl.edu">Seth Benjamin Widoff</a> -</address> -<!-- Created: Mon Jun 29 12:26:36 CDT 1998 --> -<!-- hhmts start --> -</body> -</html> |