diff options
Diffstat (limited to 'TAO/docs')
| -rw-r--r-- | TAO/docs/DIFFERENCES | 360 | ||||
| -rw-r--r-- | TAO/docs/HISTORY | 44 | ||||
| -rw-r--r-- | TAO/docs/Options.html | 293 | ||||
| -rw-r--r-- | TAO/docs/REFERENCES | 91 | ||||
| -rw-r--r-- | TAO/docs/compiler.html | 117 | ||||
| -rw-r--r-- | TAO/docs/components.html | 44 | ||||
| -rw-r--r-- | TAO/docs/configurations.html | 511 | ||||
| -rw-r--r-- | TAO/docs/forwarding.html | 111 | ||||
| -rw-r--r-- | TAO/docs/implrepo.html | 677 | ||||
| -rw-r--r-- | TAO/docs/index.html | 50 | ||||
| -rw-r--r-- | TAO/docs/leader_follower.html | 60 | ||||
| -rw-r--r-- | TAO/docs/locate_request.html | 56 | ||||
| -rw-r--r-- | TAO/docs/orbsvcs.html | 181 | ||||
| -rw-r--r-- | TAO/docs/poa_migration.html | 69 | ||||
| -rw-r--r-- | TAO/docs/reactivator.html | 21 | ||||
| -rw-r--r-- | TAO/docs/releasenotes.html | 26 | ||||
| -rw-r--r-- | TAO/docs/releasenotes/TODO.html | 627 | ||||
| -rw-r--r-- | TAO/docs/releasenotes/ec.html | 234 | ||||
| -rw-r--r-- | TAO/docs/releasenotes/index.html | 786 | ||||
| -rw-r--r-- | TAO/docs/releasenotes/orbcore.html | 503 | ||||
| -rw-r--r-- | TAO/docs/releasenotes/trader.html | 1069 |
21 files changed, 0 insertions, 5930 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/Options.html b/TAO/docs/Options.html deleted file mode 100644 index 4d8a18a88f8..00000000000 --- a/TAO/docs/Options.html +++ /dev/null @@ -1,293 +0,0 @@ -<HTML> -<HEAD> - <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><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>Environment Variables</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. -</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. -</TD></TR> -<TR> -<TD><CODE>TAO_ORB_DEBUG</CODE> <EM>which</EM></TD> -<TD> -Enables TAO debugging mode. -</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="#POA"><CODE>CORBA::POA</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> -</blockquote> - -<blockquote> -<H3><CODE>CORBA::ORB</CODE><A NAME="ORB"></A></H3> - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING= -"0"> -<TR> -<TH>Option</TH> -<TH>Description</TH></TR> -<!-- <TR NAME="ORBsvcconf"> --> -<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.</TD></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>-ORBhost</CODE> <EM>hostname</EM></TD> -<TD><a name="-ORBhost"></a>Tells the Object Adapter to listen for requests on the interface associated -with the host named <I><EM>hostname</EM></I>.</TD></TR> -<TR> -<TD><CODE>-ORBport</CODE> <EM>portspec</EM></TD> -<TD>Tells the Object Adapter to listen for requests on the port specified by -<I><EM>portspec</EM></I>, which can be a name as found in <TT>/etc/services</TT> -or a number. The default is <TT>10013</TT>.</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>, which is the traditional nonsensical object reference, -or <CODE>URL</CODE>, which looks more like a URL.</TD></TR> -<TR> -<TD><CODE>-ORBobjdemux</CODE> <EM>demux_method</EM></TD> -<TD>Specifies the method used to demultiplex to an object. The range of values -is <CODE>dynamic</CODE>, <CODE>linear</CODE>, <CODE>active</CODE>, or <CODE>user</CODE>.</TD></TR> -<TR> -<TD><CODE>-ORBtablesize</CODE> <EM>object table size</EM></TD> -<TD>Specifies the size of the object table as a positive, non-zero integer. -If not specified, the default is <TT>64</TT>.</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 system-dependent 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 system-dependent default is used.</TD></TR> -<TR> -<TD><CODE>-ORBnameserviceport</CODE> <EM>portspec</EM></TD> -<TD>Specifies which port the Naming Service is listening on.</TD></TR> -<TR> -<TD><CODE>-ORBnameserviceior</CODE> <EM>ior</EM></TD> -<TD>Specifies the IOR for the Naming Service.</TD></TR> -<TR> -<TD><CODE>-ORBcollocation</CODE> <EM>yes/no</EM></TD> -<TD>Specifies the use of collocation object optimization. Default is yes.</TD></TR> -<TR> -<TD><CODE>-ORBpreconnect</CODE> <EM>host</EM><STRONG>:</STRONG><EM>port</em>[<STRONG>,</STRONG><EM>host</EM><STRONG>:</STRONG><EM>port</em>...]</TD> -<TD><A name="-ORBpreconnect"></a>Pre-establishes a blocking connection to each listed -<em>host</em>:<em>port</em> combination. If a connection cannot -be established, a warning is announced and it continues with the -next listed. Listing the same combination multiple times will -properly establish multiple connections to that endpoint.</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.</TD></TR> -</TABLE> -</P> -</blockquote> - -<H3><CODE>CORBA::POA</CODE><A NAME="POA"></A></H3> - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> -<TR> -<TH>Option</TH> -<TH>Description</TH></TR> -<TR> -<TD><CODE>-OAid</CODE> <EM>OA Identifier</EM></TD> -<TD>Associates <I><EM>OA Identifier</EM></I> with the Object Adapter.</TD></TR> -</TABLE> -</P> -</blockquote> - -<H3><CODE>TAO_Resource_Factory</CODE><A NAME="ResourceFactory"></A></H3> - -<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.</TD></TR> -<TR> -<TD><CODE>-ORBpoa</CODE> <EM>which</EM></TD> -<TD><a name="-ORBpoa"></a>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 Root POA.</TD></TR> -<TR> -<TD><CODE>-ORBcoltable</CODE> <EM>which</EM></TD> -<TD><a name="-ORBcoltable"></a>Specify whether each ORB uses a global -(<em>which</em> = <code>global</code>) or a per-ORB -(<em>which</em> = <code>orb</code>) collocation table.</TD></TR> -</TABLE> -</P> -</blockquote> - -<H3><CODE>TAO_Default_Server_Strategy_Factory</CODE><A NAME="DefaultServer"></A></H3> - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > -<TR> -<TH>Option</TH> -<TH>Description</TH></TR> -<TR> -<TD><CODE>-ORBconcurrency</CODE> <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.</TD></TR> -<TR> -<TD><CODE>-ORBtablesize</CODE> <EM>object table size</EM></TD> -<TD>Specify the size of the object table. If not specified, the default value -is 64.</TD></TR> -<TR> -<TD><CODE>-ORBdemuxstrategy</CODE> <EM>demultiplexing strategy</EM></TD> -<TD>Specify the demultiplexing lookup strategy. The <EM>demultiplexing strategy</EM> -can be one of <CODE>dynamic</CODE>, <CODE>linear</CODE>, <CODE>active</CODE>, -or <CODE>user</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>.</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>-ORBcoltbllock</CODE> <EM>lock type</EM></TD> -<TD><a name="-ORBcoltbllock"></a>Specify the type of lock to be used for -the global collocation table. 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>-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> -<TR> -<TD><CODE>-ORBpoamgrlock</CODE> <EM>lock type</EM></TD> -<TD><a name="-ORBpoamgrlock"></a>Specify the type of lock to be used for -POA Manager 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>null</code>.</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>-ORBiiopprofilelock</CODE> <EM>which</EM></TD> -<TD> -Specify, whether to use a lock for accessing the IIOP Profile or not. -Default is <code>thread</code>, which means that a lock is used. The -second option is <code>null</code>, which means a null lock is used. -This makes sense in case of optiziations and is allowed when -no forwarding is used or only a single threaded client. -</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/compiler.html b/TAO/docs/compiler.html deleted file mode 100644 index 61ae35b0fa2..00000000000 --- a/TAO/docs/compiler.html +++ /dev/null @@ -1,117 +0,0 @@ -<html> - <!-- $Id$ --> - <head> - <title>TAO IDL compiler User's Guide</title> - </head> - -<BODY text = "#000000" -link="#0000ff" -vlink="#cc0000" -bgcolor="#ffffff"> - - <body> -<HR><P> - <h3>TAO IDL compiler User's Guide</h3> - <H2>Scope</H2> - - <P> - This document describes the options and features of TAO IDL - compiler, - it is not a reference manual or tutorial on IDL. - </P> - - <H2>Generated Files</H2> - - <P> - The IDL compiler generates 6 files from each <CODE>.idl</CODE> - file, - the file names are obtained by taking the IDL basename and - appending - <CODE>C.h</CODE>, - <CODE>C.i</CODE>, - <CODE>C.cpp</CODE>, - <CODE>S.h</CODE>, - <CODE>S.i</CODE> - and <CODE>S.cpp</CODE>; - the client stubs are declared in the <CODE>C.h</CODE> file, - the skeletons in the <CODE>S.h</CODE> file. - </P> - - <P> - Both clients and servers should link against the object files - for the stubs and skeletons, - this is needed to transparently support collocated objects. - </P> - - <H2>Options</H2> - - <P> - The IDL compiler invokes your <CODE>C</CODE> - (or <CODE>C++</CODE>) preprocessor to resolve included IDL files, - it receives the common options for preprocessors - (such as <CODE>-D</CODE> or <CODE>-I</CODE>); - but also receives other options that are specific to it. - </P> - - <P> - <TABLE BORDER="2" - CELLSPACING="2" - CELLPADDING= "0"> - <TR> - <TH>Option</TH><TH>Description</TH></TR> - <TR NAME="V"> - <TD><CODE>-V</CODE></TD> - <TD>The compiler printouts its version and exits</TD></TR> - <TR NAME="Wb"> - <TD><CODE>-Wb,</CODE><EM>option_list</EM</TD> - <TD>Pass options to the backend.</TD></TR> - <TR NAME="export_macro"> - <TD></TD> - <TD><CODE>export_macro=</CODE><EM>macro_name</EM></TD> - <TD> - The compiler will emit - <EM>macro_name</EM> - right after each <CODE>class</CODE> or <CODE>extern</CODE> - 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 NAME="export_include"> - <TD></TD> - <TD><CODE>export_include=</CODE><EM>include_path</EM></TD> - <TD> - The compiler will generate code to include - <EM>include_path</EM> at the top of the client header, - this is usually a good place to define the export macro. - </TD> - </TR> - <TR NAME="E"> - <TD><CODE>-E</CODE></TD> - <TD>Only invoke the preprocessor</TD></TR> - <TR NAME="Wp"> - <TD><CODE>-Wp,</CODE><EM>option_list</EM</TD> - <TD>Pass options to the preprocessor.</TD> - <TR NAME="D"> - <TD><CODE>-D</CODE><EM>macro_definition</EM></TD> - <TD>It is passed to the preprocessor</TD></TR> - <TR NAME="U"> - <TD><CODE>-U</CODE><EM>macro_name</EM></TD> - <TD>It is passed to the preprocessor</TD></TR> - <TR NAME="I"> - <TD><CODE>-I</CODE><EM>include_path</EM></TD> - <TD>It is passed to the preprocessor</TD></TR> - <TR NAME="A"> - <TD><CODE>-A</CODE><EM>assertion</EM></TD> - <TD>It is passed to the preprocessor</TD></TR> - <TR NAME="Y"> - <TD><CODE>-Y</CODE></TD> - <TD>It is passed to the preprocessor</TD></TR> - </TABLE> - </P> - - <hr><P> - <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> - </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 1f2390e30aa..00000000000 --- a/TAO/docs/configurations.html +++ /dev/null @@ -1,511 +0,0 @@ -<HTML> - <HEAD> - <META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> - <TITLE>Configuring TAO's Components</TITLE> - </HEAD> -<!-- $Id$ --> -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<HR><P> - -<H3 ALIGN=CENTER>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 ACE Service Configurator -framework. Thus, options are specified in the familiar -<code>svc.conf</code> file (if you want to use a different file -name, use the <a -href="Options.html#svcfonf"><code>-ORBsvcconf</code></a> -option).</p> - -<HR><P> - -<H3>Roadmap</H3> - -<blockquote> -<P>Details for the following configurations are provided.</P> - -<UL> - <li><b><a href="#comp">Configurating key components</a>:</b> - <ul> - <li><a href="#concurrency">Server Concurrency Strategy.</a> - <li><a href="#orb">ORB and other resources.</a> - <li><a href="#poa">POA.</a> - <li><a href="#coltbl">Collocation Table.</a> - <li><a href="#iiopprofile">Forwarding IIOP Profile</a> - </ul> - <li><b><a href="#examples">Configuration examples</a></b> - <ul> - <LI><A HREF="#reactive">Single-threaded, reactive model.</A> - <LI><A HREF="#tpc">Multiple threads, thread-per-connection model.</A> - <LI><A HREF="#multiorb">Multiple threads, ORB-per-Reactor-thread model.</A> - <LI><A HREF="#multiorb-tpc">Multiple threads, ORB-per-thread, - thread-per-connection model.</A> - <li><a href="#tpool">Multiple threads, thread-pool model.</a> - (Not yet implemented.) - <li><a href="#multiorb-tpool">Multiple threads, - ORB-per-thread, thread-pool model.</a> (Not yet implemented.) - <li>Each configuration has the following information:</p> - - <table border=2 width="70%" cellspacing="2" cellpadding="0"> - <tr align=left> - <th> Typical Use </th> - <td> A brief description of the scenario and its typical use. </td> - </tr> - - <tr align=left> - <th>Number of Threads</th> - <td>The number of threads used by ORB-related activities.</td> - </tr> - - <tr align=left> - <th>Thread Creator</th> - <td>Identifies the creator of the threads discussed above.</td> - </tr> - - <tr align=left> - <th>Resource Location</th> - <td>Where information on various resources is stored.</td> - </tr> - - <tr align=left> - <th>Thread task</th> - <td>Describes what task is undertaken for each thread.</td> - </tr> - - <tr align=left> - <th>Options</th> - <td>Specifies the options for each service in order to utilize this configuration.</td> - </tr> - </table> - </ul> -</UL> - - -</blockquote> - -<HR><P> -<h3>Configuring key components<a name="comp"></a></h3> - -<ul> - <li><b><a name="concurrency">Server concurrency strategy</a></b> - specifies the concurrency strategy an ORB uses. It says nothing - about how many ORBs (or, threads) are there in a process.<p> - - <ul> - <li><code>reactive</code>: The ORB handles requests - reactively, i.e., the ORB runs in one thread and service - multiple requests/connections simultaneously using - "<code>select</code>" call. You can have multiple ORBs - accepting requests reactively and running in separate - threads.<p> - - <li><code>thread-per-connection</code>: The ORB handles new - connections by spawning a new thread whose job is to - service requests coming from the connection. The new - threads inherits all properties from the ORB threads (see - below.) <p> - - <li><code>thread-pool</code> (not yet implemented): ... to be - continued ... <p> - - </ul><p> - - <li><b><a name="orb">ORB and other resources.</a></b><p> - - <ul> - <li><code>global</code>: There's only one ORB process-wide. - <code>ORB_init () </code>must be called only once. Every - thread accesses the same ORB. <p> - - <li><code>tss</code>: When using <code>tss</code> ORB, the - programmer is responsible for spawning the ORB threads and - setting up the ORB by calling <code>ORB_init ()</code> for - each ORB threads. Any ORB spawned thread (i.e., thru - thread-per-connection) shares the same resource the - spawning ORB uses.<p> - - </ul><p> - - <li><b><a name="poa">POA.</a></b><p> - - <ul> - <li><code>global</code>: All ORBs share the same POA. The - advantage of using a global POA is that once an object is - registered to the POA under an ORB, it can be externalized - from other ORB.<p> - - <li>per ORB (<code>tss</code>): Each ORB has its own POA, - which means, the programmer should also instantiate the POA - for each ORB (otherwise, a default RootPOA gets created, - which might not be what you what and thus, is discouraged.)<p> - - </ul><p> - - <li><b><a name="coltbl">Collocation Table:</a></b> <sup>*</sup>Care - must be taken when using CORBA objects to control the ORB - directly. For you are actually executing the collocated object, - not in the object's ORB context, but in the calling ORB's - context.<p> - - <ul> - <li><code>global</code>: Process keeps a global collocation - table which contains tuples of listening endpoint and its - corresponding RootPOA. <p> - - <LI>per ORB (<code>tss</code>): At this moment, since TAO only - supports one listening endpoint per ORB, there is no - per-ORB collocation Table. Checking of collocated objects - is done by comparing object's IIOP profile and the calling - ORB's listening endpoint.<p> - - </ul><p> - - <li><b><a name="iiopprofile">Forwarding IIOP Profile:</a></b> - In the case of multiple threads using the same <code>CORBA::Object</code> and - using forwarding, it is necessary to protect the forwarding - <code>IIOP_Profile</code>, which is part of the <code>IIOP_Object</code>, - which is part of the CORBA::Object against multiple access. Therefore - a mutex lock is used by default to ensure proper access. Using - the switch <code>-ORBiiopprofilelock</code> this policy can - be deactivated specifying <code>-ORBiiopprofilelock null</code>. - A motivation to do this might be performance reasons in cases, - where no forwarding is used or no multithreading with access - to shared <code>CORBA::Object</code>'s. Deactivating forces the ORB - to use a null mutex, which does introduce only a very small - overhead, compared with overhead introduced by a regular mutex lock. - <p> - - -</ul> - - - -<HR><P> -<H3>Configuration Example<a name="examples"></a></H3> - -<UL> -<LI>Single-threaded, reactive model.<A NAME="reactive"></A> - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> - <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 align=left> - <th>Number of Threads</th> - <td>1</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>OS or whomever creates the main ORB thread in a process.</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Resources are stored process-wide.</td> -</tr> - -<tr align=left> - <th>Thread task</th> - <td>The single thread processes all connection requests and CORBA messages.</td> -</tr> - -<tr align=left> - <th>Options</th> - <td> - <code>TAO_Resource_Manager</code>: <code>-ORBresources global</code><br> - <code>TAO_Server_Strategy_Factory</code>: <code>-ORBconcurrency reactive</code> - </td> -</tr> -</table> -</p> - -<LI>Multiple threads, thread-per-connection model.<A NAME="tpc"></A> - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> -<tr align=left> - <th>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. -</tr> - -<tr align=left> - <th>Number of Threads</th> - <td>1 plus the number of connections.</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>Programmer must set up the main thread which is - responsible to create new threads for new connections.</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Process-wise.</td> -</tr> - -<tr align=left> - <th>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 align=left> - <th>Options</th> - <td> - <code>TAO_Resource_Manager</code>: <code>-ORBresources global</code><br> - <code>TAO_Server_Strategy_Factory</code>: <code>-ORBconcurrency thread-per-connection</code> - </td> -</tr> - -</table> -</p> - -<LI>Multiple threads, ORB-per-thread model.<A NAME="multiorb"></A> - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> -<tr align=left> - <th>Typical Use</th> - <td>In this configuration, there multiple ORBs per process each - running in its own thread. 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 align=left> - <th>Number of Threads</th> - <td>The number of ORBs.</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>The main process (thread).</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Thread specific.</td> -</tr> - -<tr align=left> - <th>Thread task</th> - <td>Service the requests from associating ORB.</td> -</tr> - - <tr align=left> - <th>Options</th> - <td> - <code>TAO_Resource_Manager</code>: <code>-ORBresources tss</code><br> - <code>TAO_Server_Strategy_Factory</code>: <code>-ORBconcurrency reactive</code> - </td> -</tr> -</table> -</p> - -<LI>Multiple threads, ORB-per-thread, thread-per-connection -model.<A NAME="multiorb-tpc"></A></H3> - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> -<tr align=left> - <th>Typical Use</th> - <td>This approach provides a range of thread priorities plus connections - that don't interfere with each others.</td> -</tr> - -<tr align=left> - <th>Number of Threads</th> - <td>Number of ORBs plus number of connections.</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>Main threads creates threads running ORBs. They, in - turns, create connection handling threads.</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Thread specific.</td> -</tr> - -<tr align=left> - <th>Thread task</th> - <td>There are ORB threads which handle connection requests - and handler threads which service requests form - establiched connections.</td> -</tr> - -<tr align=left> - <th>Options</th> - <td> - <code>TAO_Resource_Manager</code>: <code>-ORBresources tss</code><br> - <code>TAO_Server_Strategy_Factory</code>: <code>-ORBconcurrency thread-per-connection</code> - </td> -</tr> - -</table> -</p> - -<LI><A NAME="tpool">Multiple threads, thread-pool model.</A> -(Not yet implemented.) - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> -<tr align=left> - <th>Typical Use</th> - <td>This model implements a highly optimized thread pool that - minimizes context switching, synchronization, dynamic memory - allocations, and data movement between threads.</td> -</tr> - -<tr align=left> - <th>Number of Threads</th> - <td>The number of threads used by ORB-related activities.</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>Identifies the creator of the threads discussed above.</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Where information on various resources is stored.</td> -</tr> - -<tr align=left> - <th>Thread task</th> - <td>Describes what task is undertaken for each thread.</td> -</tr> -</table> -</p> - -<LI>Multiple threads, ORB-per-thread, thread-pool model.<A -NAME="multiorb-tpool"></A> (Not yet implemented.) - -<p> -<table border=2 width="90%" cellspacing="2" cellpadding="0"> -<tr align=left> - <th>Typical Use</th> - <td>A brief description of the scenario and its typical use.</td> -</tr> - -<tr align=left> - <th>Number of Threads</th> - <td>The number of threads used by ORB-related activities.</td> -</tr> - -<tr align=left> - <th>Thread Creator</th> - <td>Identifies the creator of the threads discussed above.</td> -</tr> - -<tr align=left> - <th>Resource Location</th> - <td>Where information on various resources is stored.</td> -</tr> - -<tr align=left> - <th>Thread task</th> - <td>Describes what task is undertaken for each thread.</td> -</tr> -</table> -</p> - -</UL> -</blockquote> - -<HR> - -<H3 ALIGN=CENTER>Hints</H3> - - <P> - 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. - </P> - - <UL> - <LI> - <P><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 global 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. - For example, - object activation can be simplified by using a global POA; - the careful reader will wonder how could global POA be - useful in anyway since it will require locks and thus - introduce priority inversions again; - some applications activate all their objects beforehand so - locks in the POA are not always needed; - other applications only activate a few objects after - startup, - so they can use a child POA with the right locking policy - for the dynamic servants and the root poa (with no locking) - for the majority of the servants. - </P> - <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> - <LI><B>Collocation tables</B> - Why could the application what a non-global collocation table? - 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> - </UL> - -<P><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/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 384c0ff1629..00000000000 --- a/TAO/docs/implrepo.html +++ /dev/null @@ -1,677 +0,0 @@ -<!-- $Id$ --> -<html> - -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<title>TAO Implementation Repository</title> -</head> - -<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#CC0000"> - -<hr> - -<h1>TAO Implementation Repository </h1> - -<p>Revision 3.04 - August 5, 1998</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.03 - -<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 - -<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.cs.wustl.edu/~schmidt/binding.pdf.gz">Binding, Migration, and -Scalability in CORBA</a>" [Henning]. This paper describes the following three -functions of the Implementation Repository: - -<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. 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. - -<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 <a -href="http://www.cs.wustl.edu/~schmidt/michi.pdf">Henning</a> paper, he mentions the use -of a <em>server name</em> as the index for the table maintained by the Implementation -Repository. </p> - -<p>The virtual server does not refer to the executable but instead to a group of objects. -An executable may have one or more virtual servers on 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 also 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 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>In TAO, Transient object references will have a TimeStamp to ensure uniqueness. -Likewise, persistent object references will have a server name to identify them in the -Implementation Repository.</p> - -<p>TAO will support two difference classes of Persistent IORs. For servers that move -around or need to be restarted often, the IOR will actually 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.</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>If the server is expected to remain in the same host/port for a long time, then the 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.</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 it 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: - -<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>Another design of an Implementation Repository uses an Object Reference that points to -the Implementation Repository instead of pointing directly to the persistent object. This -extra level of indirection is used by the Implementation Repository to start the server -(if needed), and then uses the Location Forwarding mechanism 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. - -<ol> - <li>Now the server will start up and call <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. - -<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: - -<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 also have added functionality where other Implementation Repositories that are -specified on the command-line, in environment variables, or found through multicast will -also be contacted. - -<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>Now connect to any Implementation Repositories that have been found.</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>Back to the <a href="index.html">TAO documentation</a> page.</p> -<!--#include virtual="/~schmidt/cgi-sig.html" --> -</body> -</html> diff --git a/TAO/docs/index.html b/TAO/docs/index.html deleted file mode 100644 index ed4e9bb731a..00000000000 --- a/TAO/docs/index.html +++ /dev/null @@ -1,50 +0,0 @@ -<html> - -<head> -<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> - <dd> </dd> - <dt><a HREF="http://www.cs.wustl.edu/~schmidt/events_tutorial.html">Event Service Tutorial</a></dt> - <dd> </dd> - <dt><a HREF="http://www.cs.wustl.edu/~schmidt/TAO/index.html">TAO Viewgraphs</a></font></dt> - </dl> - </td> - <td><font SIZE="+1"><dl> - <dt><a HREF="components.html">Component Configuration</a> </dt> - <dd> </dd> - <dt><a HREF="compiler.html">TAO IDL Compiler Options</a> </dt> - <dd> </dd> - <dt><a HREF="orbsvcs.html">ORB Services Directories</a></font> </dt> - </dl> - </td> - <td><font SIZE="+1"><dl> - <dt><a HREF="releasenotes/index.html">Release Notes</a> </dt> - <dd> </dd> - <dt><a HREF="poa_migration.html">POA Migration Notes</a> </dt> - <dd> </dd> - <dt><a HREF="implrepo.html">Implementation Repository</a> </font></dt> - </dl> - </td> - </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/orbsvcs.html b/TAO/docs/orbsvcs.html deleted file mode 100644 index f16fcafd7b5..00000000000 --- a/TAO/docs/orbsvcs.html +++ /dev/null @@ -1,181 +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/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> - </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>Event_Service</LI> - <LI>Naming_Service</LI> - <LI>Scheduling_Service</LI> - <LI>Trading_Service</LI> - </UL> - - <P>In the future we plan to use a single binary and ACE Service - Configurator and keep a single binary.</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>Event_Latency</CODE></TD> - <TD>Test the Event Service and measure end-to-end latency, - it also uses the Scheduling and Naming services.</TD></TR> - <TR> - <TD><CODE>EC_Multiple</CODE></TD> - <TD>Connect two Event Channels using the - <CODE>EC_Gateway</CODE>, - measure latency, utilization and minimum spacing.</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>An advanced test of the Naming Service.</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 very simple Naming Service test.</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_Service</CODE></TD> - <TD>Implementation of the Trading 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 5623a283698..00000000000 --- a/TAO/docs/poa_migration.html +++ /dev/null @@ -1,69 +0,0 @@ -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> - <TITLE>Migrating from the BOA to the POA</TITLE> -</HEAD> - -<BODY text = "#000000" -link="#0000ff" -vlink="#cc0000" -bgcolor="#ffffff"> - -<HR><P> -<H3>Migrating from BOA to POA</H3> - -<UL> -<LI><EM><B>Client side</b></EM><P> -<ul> -<li>Very little has changed, and some have not needed any changes.</li><P> -<li>You'll have to insure that the Makefile includes .o's for both the server -and client; this is necessary to support collocation.</li> <P> -</ul> - -<LI><EM><B>Server side</B></EM><P> -<UL> -<li>POA_init() is replaced with resolve_initial_references("RootPOA") followed -by a _narrow operation.</li><P> -<li>The implementation no longer inherits from the client-side stub; they -inherit from PortableServer::ServantBase. The implications of this are (a) if -you want a object reference for that, you must use the _this() method.</li><P> -<li>Object ID's are assigned by the POA unless you activate the servant with a -specific ID; IDL_Cubit 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 activate_object* methods on a POA or - calling _this() 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 <const char*> 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 which have to change and I -didn't note them, please send them to me. Perhaps we can work together on the -ultimate migration document. <P> -</UL> -</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/TODO.html b/TAO/docs/releasenotes/TODO.html deleted file mode 100644 index 786f173a0df..00000000000 --- a/TAO/docs/releasenotes/TODO.html +++ /dev/null @@ -1,627 +0,0 @@ -<HTML> -<HEAD> - <TITLE>TAO TODO List</TITLE> -</HEAD> - <BODY TEXT="#000000" BGCOLOR="#FFFFFF"> - <!-- $Id$ --> - <CENTER><HR></CENTER> - - <CENTER> - <H3>General TODO list for TAO</H3> - </CENTER> - - <P> - This document presents a general TODO list for TAO, - 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. - Hopefully as more people gets involved it will become more - organized. - </P> - <P> - Last Updated: $Date$ $Revision$ - </P> - - <CENTER><HR></CENTER> - - <CENTER> - <H4>Pending Tasks</H4> - </CENTER> - - <UL> - <LI>Add suspend and resume operations to the PushConsumerProxy - and PushSupplierProxy interfaces, following the Notification - Service spec. - </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 ()). - </LI> - - <LI>The IDL compiler gets confused with paths in NT, this may be - due to my changes to report errors correctly. - </LI> - - <LI>The do_static_call() and do_dynamic_call() methods should - use an array of void* (in the first case static and generated - by the IDL compiler); - this will remove the problems with g++ and probably work - faster. - </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.... - </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). - </LI> - - <LI>Further optimize memory allocation by using a memory pool - for the incoming CDR stream. - </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). - </LI> - - <LI>Add compiled marshalling - <BR>[STATUS] Andy is working on this. - </LI> - - <LI>Use active demuxing in the POA - </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 - </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 - </LI> - - <LI>We need some TAO_TRY_* macro to encapsulate a common use of - the CORBA::Environment argument: checking if it contains an - exception and then returning. - </LI> - - <LI>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. - </LI> - - <LI>IDL compiler front-end should be case insensitive (actually - it should flag identifiers that only differ by case as a - conflict). - </LI> - - <LI>Support for 64bit longs in the IDL compiler - </LI> - - <LI>The operation tables do not need to be statics, they could - be created on creation of the first servant of that type. - </LI> - - <LI>Are nested upcalls in different concurrency models, like - thread-per-connection working? - </LI> - - <LI>Add an option to the IDL-compiler (e.g. -rp) meaning - "generate relative include paths". - </LI> - - <LI>The IDL compiler should generate the files locally (maybe - with an option). - </LI> - - <LI>Add options to the IDL compiler to set the suffixes. - </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 - </LI> - - <LI>Support for unions with default cases (implicit or explicit) - in the IDL compiler is incomplete. - </LI> - - <LI>It seems that some memory is leaked from the ORB cached - connector. - </LI> - - <LI>Support for fixed in the IDL compiler - </LI> - - <LI>CDR stream support for wchar is flaky. - </LI> - - <LI>Add a corbafwd.h header file to eliminate the deep (and - recursive) header dependencies in TAO. - </LI> - - <LI>Prepare the 1.0 release: - <UL> - <LI>Integrate the compiled marshalling approach. - </LI> - <LI>Verify the GPERF is working in all the relevant - platforms. - </LI> - <LI>Integrate active demux of operations? - </LI> - </UL> - </LI> - - <LI>Support the Sun bootstrapping mechanism for the Naming - Service - </LI> - - <LI>Add a -ORBlogfile flag so we can set the ACE_ERROR and - ACE_DEBUG output destination in all TAO applications - </LI> - - <LI>Add the _raise() method to the exceptions... - </LI> - - <LI>Add support for multiple Profiles in the ORB (completing the - IIOP 1.0 support) - </LI> - - <LI>Purify, purify, purify the EC - </LI> - - <LI>Quantify the EC. - </LI> - - <LI>Support several calls to ORB_init() on the same thread. - </LI> - - <LI>Support IIOP 1.1 in the ORB - </LI> - - <LI>Use the IIOP 1.1 profile info to pass QoS info and use it to - preserve end-to-end QoS. - </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). - </LI> - - <LI>Call ORB_init() in the EC threads? - [The dispatching threads for Boeing] - </LI> - - <LI>Build an EC example that uses all the cool features - (multiple ORBs on each process, collocated EC and Scheduling - service, Naming, etc.) - </LI> - - <LI>Extend the Concurrency Service (or create a new one) that - allow us to have global "barriers" to synchronize EC - startup/shutdown. - </LI> - - <LI>Correlation in the EC has a bug [?] - Build regression tests for the EC features (filtering, - correlation, timers, etc). - </LI> - - <LI>Build a COS Event Channel on top of the RTEC Event Service. - </LI> - - <LI>Check what is failing in $TAO_ROOT/tests/CDR/tc. - </LI> - - <LI>Debug interval computation in Linux (and NT?) - </LI> - - <LI>Remove the uneeded methods from CORBA::Object - </LI> - - <LI>Implement operation demuxing for clients. - </LI> - - <LI>Study the CORBAlite spec and see how we could implement it - with TAO, considering dynamic and static configurations for - the full CORBA support - </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 <any> or <fixed> 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> - </LI> - - <LI>Consider decompositions of the ORB that would allow - dynamically linked plug-ins, examples of things that would be - easy to implement as plugins: - <UL> - <LI>SSL support - </LI> - <LI>UNIX socket support - </LI> - </UL> - Things that would be really hard: - <UL> - <LI>Dynamically load the support for costly features, as the - ImplRepo or Location Forwarding. - </LI> - <LI>Dynamically configure POA with or without support for - holding state. - </LI> - </UL> - </LI> - - <LI>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 Servanst (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. - </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. - </LI> - - <LI>The current scheme for the orbsvcs leaves the user without - control 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. - </LI> - - <LI>Cleanup the IDL structures for subscriptions, publications, - etc. (in the EC). - </LI> - - <LI>Resolve the Typecode::equal dilemma: is it structural or - type equivalence? Or a mixin? - </LI> - - <LI>Automate EC multicast group usage. This probably requires - some kind of server that mantains the realtion between event - type/source and the mcast groups. - </LI> - - <LI>Improve configuration support in the EC, give an example of - a single threaded EC, support different dispatching - strategies, etc. - </LI> - - <LI>Use the Service_Configurator to dynamically load the EC - Module_Factory thus making it really configurable. - </LI> - - <LI>The current scheme for Typecode (keeping a CDR buffer with - their representation) is broken. - </LI> - - <LI>We must support DynAny. - </LI> - - <LI>We must support a IFR. - </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. - </LI> - - <LI> - The current implementation 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. - </LI> - </UL> - - <CENTER> - <H4>Completed Tasks</H4> - </CENTER> - - <UL> - <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] - </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). - </LI> - - <LI>Optimize Octet Sequences. - <BR>[DONE] - </LI> - - <LI>Obtain results for the EC_Multiple test. - <UL> - <LI>Latency seems OK. - </LI> - <LI> Overhead: need lower priority for scavenger thread. - </LI> - </UL> - </LI> - - <LI>Debug EC_Multiple. - </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 - </LI> - - <LI>Remove the SOLARIS2 macro from the TAO_IDL compilation. - <BR>[DONE] - </LI> - - <LI>Remove the preemption_prio message from Scheduling_Service. - </LI> - - <LI>The ORB core should be able to choose the right port for us - (in other words -ORBport 0) should work. - <BR>[DONE] - </LI> - - <LI>Client side optimization for Octet Sequences. - <BR>[DONE] - </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. - </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. - </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. - </LI> - - <LI>Support a chain of Message Blocks in Output CDRs and use - writev() to write them. - <BR>[DONE] - </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). - </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. - </LI> - - <LI>Show an example of the sequence<octet> and CDR streams. - <BR>[DONE] But the example could also include the marshalling of - plain C++ types. - <BR>[DONE too] - </LI> - - <LI>Test anys in the EC. - <BR>[DONE] Michael reported that they work OK on NT. - </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. - </LI> - - <LI>Unbind the EC and scheduling service from the Naming - Service. - <BR>[DONE] For the Event_Service and the examples. - </LI> - - <LI>Optimize oneways by not allocating the memory for the return - buffers. - <BR>[DONE] Added different Invocation classes for each case. - </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. - </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. - </LI> - - <LI>Fix the ACE_Thread_Condition madness. - <BR>[DONE] We changed ACE so ACE_SYNCH_CONDITION expands to - ACE_Condition_Thread_Mutex - </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] - </LI> - - <LI>Reference counting for Typecodes is completely broken. - <BR>[DONE] - </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) - </LI> - - <LI>The octet sequence optimization causes problems when Anys - get into the game. - <BR>[DONE] Seth reported that the problem was not real. - </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. - </LI> - - <LI>Improve error messages in the IDL compiler. - <BR>[DONE] At least the filename is correct now. - </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. - </LI> - - <LI>Prepare the 0.2 release: - <UL> - <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> - </UL> - <BR>[DONE] At last! - </LI> - - <LI>Move this list to the release notes. - </LI> - </UL> - -<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 6f84f2ec177..00000000000 --- a/TAO/docs/releasenotes/ec.html +++ /dev/null @@ -1,234 +0,0 @@ -<!-- $Id$ --> - -<HTML> - <HEAD> - <TITLE>Event Service Status</TITLE> - </HEAD> - -<BODY TEXT="#000000" BGCOLOR="#FFFFFF"> - <BODY> - <H3>Event Service Status</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> - Added a prototype Consumer and Supplier that can send events - though multicast groups (or regular UDP sockets). - </LI> - <LI> - 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. - </LI> - </UL> - - <H3>Known issues:</H3> - <DL> - <DT><EM>The schedule cannot be downloaded</EM></DT> - <DD> - The Scheduling Service seems to compute proper schedules, - but it is not possible to download them, - apparently there is a marshalling problem for sequences of - complex structures. - - <P>Due to this problem we have been unable to test the - run-time scheduler and performance it is impossible to - complete performance measurements and optimizations: - the (global) scheduling service latency and overhead is at - least as large as the EC itself.</P> - </DD> - - <DT><EM>Run-time scheduler requires re-link</EM></DT> - <DD> - During a normal execution of the system - there is no - need to use the a global Real-time Scheduling Service, - a faster, - collocated implementation for the service is available. - Obviously the scheduling information is precomputed in some - config run. - - <P>Unfortunately the current scheme requires a relink of all the - involved applications against the generated tables for the - run-time scheduling service.</P> - - <P>We should be able to download the schedule to the interested - parties, - without need for a separate link phase. - This will simplify and speed up the developing cycle, - but requires a (small and fixed) amount of dynamic memory - allocation. - It could be interesting to "save" the schedule computation in - some persistent form, - so startup cost are lower too.</P> - - <P>The current design contemplates a config run were a global - consumer accumulates the QoS requirements of all the objects, - next an external utility is used to force a computation and - save of the schedule. - In future executions - the global scheduler pre-loads this schedule and - the clients simply download the precomputed schedule, - and all scheduling queries are to a local scheduling service, - without any further contact to the global instance.</P> - </DD> - - <DT><EM>Users have no control over service - collocations</EM></DT> - <DD> - The user should have complete control of services collocation, - using ACE Service Configurator; - currently the services must be explicitly instantiated by the - user. - </DD> - - </DL> - - <H3>Examples</H3> - - <P>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 - <CODE>Event_Latency</CODE>, - below are the basic instructions to run it:</P> - - <OL> - <LI> Compile everything under <CODE>$TAO_ROOT/orbsvcs</CODE>, this - needs, obviously, <CODE>$TAO_ROOT/tao</CODE> and - the IDL compiler in <CODE>$TAO_ROOT/TAO_IDL</CODE>.</LI> - - <LI><P>Run the naming service, the scheduling service, the event service - and the test in - <CODE>$TAO_ROOT/TAO/orbsvcs/tests/Event_Latency</CODE>; - remember to give a different port to each one, - using the <CODE>-ORBport</CODE> option. As in:</P> - - <CODE> - <P> - $ cd $TAO_ROOT/orbsvcs - </P> - <P> -$ cd Naming_Service ; ./Naming_Service -ORBport 10000 & - </P> - <P> -$ cd Event_Service ; ./Event_Service -ORBport 0 & - </P> - <P> -$ cd tests/Event_Latency ; ./Event_Latency -ORBport 0 -m 20 -j & - </P> - </CODE> - - <P> - You may want to run each program in a separate window. - Try using a fixed port number for the <CODE>Naming - Service</CODE> so you can use the <CODE>NameService</CODE> - environment variable. - </P> - - <P> - The script <CODE>start_services</CODE> - in <CODE>$TAO_ROOT/orbsvcs/tests</CODE> can help with - this. - </P> - - </LI> - - <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> - - <P>Another example is <CODE>EC_Multiple</CODE>, - numerous examples on how to run this test can be found in the - scripts located in - <CODE>$TAO_ROOT/orbsvcs/tests/EC_Multiple</CODE>.</P> - - <H3>Features in previous releases</H3> - - <UL> - <LI> - <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> - - <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> - - <P> - Locally the proxy connects as a supplier, - publishing all the events it has register for. </P> - - <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> - - <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> - </LI> - - <LI> <P> - We use the COS Time Service types (not the services) to - specify time for the Event Service and Scheduling Service.</P> - </LI> - - <LI>The <CODE>Gateway</CODE> to connect two event channels was - moved from a test to the library. - The corresponding test (<CODE>EC_Multiple</CODE>) has been - expanded and improved.</LI> - - <LI> - The user can register a set of <CODE>EC_Gateways</CODE> with - the <CODE>EventChannel</CODE> implementation, the event - channel will automatically update the subscription list as - consumers subscribe to the EC. - </LI> - <LI> - The code for consumer and supplier disconnection was - improved and seems to work without problems now - </LI> - <LI> - The <CODE>Event_Service</CODE> program creates a collocated - <CODE>Scheduling Service</CODE> this works around a problem - in the ORB when running on multiprocessor. - </LI> - <LI> - Startup and shutdown were revised, the event channel - shutdown cleanly now. - </LI> - <LI> - Added yet another example - (<CODE>$TAO_ROOT/orbsvcs/tests/EC_Throughput</CODE>), 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. - </LI> - </UL> - - </BODY> -</HTML> diff --git a/TAO/docs/releasenotes/index.html b/TAO/docs/releasenotes/index.html deleted file mode 100644 index e103be67a88..00000000000 --- a/TAO/docs/releasenotes/index.html +++ /dev/null @@ -1,786 +0,0 @@ -<HTML> -<HEAD> - <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> - <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; I; SunOS 5.5.1 sun4u) [Netscape]"> - <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="orbcore.html">ORB Core</A></LI> - -<LI> -<A HREF="#idl">IDL Compiler</A></LI> - -<LI> -<A HREF="#poa">Portable Object Adapter</A></LI> - -<LI> -<A HREF="#nservices">CORBA Naming Service</A></LI> - -<LI> -<A HREF="ec.html">CORBA Event 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 Control Service</A></LI> - -<LI> -<A HREF="#logging">CORBA Logging Service</A></LI> - -<LI> -<A HREF="#implrepo">Implementation Repository</A></LI> - -<LI> -<A HREF="#av">CORBA Audio/Video Control Service</A></LI> - -<LI> -<A HREF="#apps">Test & Example Applications</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><!--#include virtual="orbcore.html" --> -<HR> -<H3> -<A NAME="idl"></A>IDL Compiler</H3> -Point of contact: <A HREF="mailto:gokhale@cs.wustl.edu">Aniruddha Gokhale</A> - -<P>Current status: (As of July 31st, 1998.) -<UL> -<LI> -Anonymous arrays inside structs are supported. However, they are not yet -supported inside unions.</LI> - -<LI> -Perfect Hashed Operation Lookup Strategy has been added to the IDL Compiler. --P flag to the <tao_idl>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> -Support for Arrays is refined in terms of the code generated for parameters -inside stubs and skeletons.</LI> - -<LI> -Significantly improved the support for unions. The default case is yet -to be handled.</LI> - -<LI> -Added support for Arrays. Right now, support for typedefed arrays is in. -Still needs testing.</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 "typedef sequence <char>CharSeq;", 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> -Introduced tests for object references to TAO. Still incomplete.</LI> - -<LI> -Param_Test example is able to test string sequences, fixed structs, variable -sized structs and nested structs</LI> - -<LI> -Param_Test test suite can now test fixed structs and string sequences.This -needed bug fixes to TAO ORB core.</LI> - -<LI> -A new test to test all the parameter passing modes for a number of data -types has been added. At this point in time, it tests primitive types and -strings. Other tests will be added. Bugs discovered thru these tests have -been fixed.</LI> - -<LI> -Very preliminary support for arrays. Not working yet.</LI> - -<LI> -Many bugs associated with stub generation fixed. This included support -for return values that are variable sized IDL types. Unions improved.</LI> - -<LI> -Support for sequences of strings and object references added. However, -it is not tested yet so there may be some bugs. We should have these fixed -in a day or so.</LI> - -<LI> -Support for handling exceptions added. TAO does not use direct C++ exceptions. -Instead it uses the CORBA::Environment based approach.</LI> - -<LI> -Sequences as out parameters have been tested in the IDL_Cubit example. -A test suite is currently being built to test all the parameter passing -modes on a variety of IDL data types.</LI> - -<LI> -Support for attributes completed. Not tested yet.</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> -The compiler generates correct code for COSS Naming service and it runs -properly. Correct code also gets generated for the Event Channel program</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> -IN, INOUT, and OUT object reference parameters are now supported properly. -We think the same approach should work for sequences, structs, and unions.</LI> - -<LI> -Many IDL constructs supported including primitive types, typedefs, sequences, -structures, and unions.</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> -Generated code closely follows the C++ Mapping specified in the POA Specification -(ORBOS/97-05-15).</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</TT> <TT>-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> -</UL> -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> -TypeCode generation for multidimensional arrays and indirected typecodes -is still a problem.</LI> - -<LI> -Unions with default cases yet to be handled</LI> - -<LI> -Deal with names in the IDL definition that are C++ keywords.</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> - -<LI> -tao_idl generates code for a *.idl file only inside the directory where -the *.idl resides. However, it may be required to generate code elsewhere -i.e., in the directory where the compiler was invoked. Thanks to Tom Richards -(tomr@MCMEnterprise.com) for this suggestion.</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> -Improve IDL compiler to generate compiled form of stubs/skeletons.</LI> - -<LI> -Fix bugs in the SunSoft IDL front-end we've uncovered. These primarily -include support for Unions.</LI> - -<LI> -Add command line options to TAO IDL. These options will decide what strategy -to use for operation name demultiplexing. Another option may decide whether -to use the interpretive IIOP engine or generate compiled stubs/skeletons.</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> -</UL> - -<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. -<HR></LI> - -<H3> -<A NAME="poa"></A>Portable Object Adapter</H3> -Point of contact: <A HREF="mailto:irfan@cs.wustl.edu">Irfan Pyarali</A> - -<P>Current Status: -<UL> -<LI> -TAO fully supports the POA spec. This section will carry updates as available.</LI> -</UL> -Known issues: -<DL> -<DT> -<I>Support for collocation is not complete.</I></DT> - -<DD> -If an object which should be collocated is created via <TT>string_to_object</TT>, -it is created as a remote object rather than collocated.</DD> -</DL> -Critical work: -<UL> -<LI> -None.</LI> -</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> - -<LI> -Provide extensions of the specification to ensure real-time delivery of -messages.</LI> -</UL> - -<HR><!--#include virtual="ec.html" --> -<HR> -<H3> -<A NAME="nservices"></A>CORBA Naming Service</H3> -Point of contact: <A HREF="mailto:sergio@cs.wustl.edu">Sergio Flores-Gaitan</A> -and <A HREF="mailto:marina@cs.wustl.edu">Marina Spivak</A> - -<P>Current status (as of Feb 27th): -<UL> -<LI> -The Naming Service implementation is complete.</LI> -</UL> -Future work: -<UL> -<LI> -Currently the bindings are stored as a table in memory. Future work will -include a persistent database to store the bindings.</LI> - -<LI> -Replication of the bindings to other Naming Service's currently running. -It will probably be modeled after the LDAP Multi-Master Replication Protocol. -For more information on this replication protocol please read <A HREF="ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-mult-mast-rep-02.txt">LDAP -Multi-Master Replication Protocol</A></LI> -</UL> -For general documentation on the Naming Service please read <A HREF="ftp://www.omg.org/pub/docs/formal/97-07-12.pdf">The -Naming Service Specification</A>. - -<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 TAO Trading Service is a transient 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: -<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> -For general documentation of the Trading Service, please read <A HREF="http://www.omg.org/corba/sectrans.htm#trader">The -Trading Service Specification.</A> - -<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 May 02, 1998) -<BR> -<BR>All the interfaces of this service have been implemented. Please -go through the test examples at $TAO/orbsvcs/tests/CosPropertyService. -Property Service is now used by the AVStreams that is currently being -developed for TAO. More testing is being done. - -<P>For general documentation of the Property Service, please read <A HREF="http://www.omg.org/corba/sectrans.htm#prop">The -Property Service Specification.</A> - -<P> -<HR> -<H3> -<A NAME="implrepo"></A>Implementation Repository</H3> -Point of contact: <A HREF="mailto:brunsch@cs.wustl.edu">Darrell Brunsch</A> - -<P>Current status (as of July 23, 1998) - -<P>Here is a brief list of my goals (and the dates completed). For more -information, please see the <A HREF="../implrepo.html">Implementation Repository -documentation</A>. -<UL> -<LI> -Create the base test client and server programs [7/17]</LI> - -<LI> -Add an IR that forwards server requests [7/23]</LI> - -<LI> -Have the server register its IOR with the IR</LI> - -<LI> -Have the server exit after every call, so it is restarted each time</LI> - -<LI> -Add the ping object to the server</LI> - -<LI> -Add in shutdown calls to test ping objects</LI> - -<LI> -Change IOR format</LI> - -<LI> -Add in support for server names</LI> - -<LI> -Make the IR forward any request</LI> - -<LI> -Add another server</LI> -</UL> -Other goals: -<UL> -<LI> -Implement the IDL Interface for the IR</LI> - -<LI> -Move this stuff into the POA</LI> - -<LI> -Multiple Profiles</LI> - -<LI> -POA extension</LI> - -<LI> -Persistence</LI> -</UL> -Future Goals: -<UL> -<LI> -TAO client-side optimization with restarted servers</LI> - -<LI> -Server security (checksums)</LI> - -<LI> -Helper Application</LI> - -<LI> -Federation of IRs</LI> - -<LI> -DLLs</LI> -</UL> - -<HR> -<H3> -<A NAME="cservices"></A>CORBA Concurrency Control Service</H3> -Point of contact: <A HREF="mailto:tworm@cs.wustl.edu">Torben Worm</A> - -<P>Current status (as of May 3rd): -<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 Control Service with transactions</LI> -</UL> -For general documentation of the Concurrency Control Service, please read -<A HREF="http://www.omg.org/corba/sectrans.htm#concur">The Concurrency -Control Service Specification.</A> - -<P> -<HR> -<H3> -<A NAME="logging"></A>CORBA 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 WIDTH="100%"> -<H3> -<A NAME="av"></A>CORBA Audio/Video Control Service</H3> -Point of contact: <A HREF="mailto:sumedh@cs.wustl.edu">Sumedh Mungee</A> -and <A HREF="mailto:naga@cs.wustl.edu">Nagarajan Surendran</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>. - -<P>The audio/video streaming service has been implemented in the light -profile. An MPEG-1 application which streams mpeg-1 video and mpeg-1 audio -separately has been developed using the service. This application currently -works only for Unix platforms. - -<P>Current Status: -<UL> -<LI> -Implemented the handshake mechanism between the consumer and supplier of -the stream.</LI> - -<LI> -Implemented a simple version of the stream controller (StreamCtrl).</LI> - -<LI> -Implemented the VDev and StreamEndPoint base class functionality.</LI> - -<LI> -Implemented the MMDevice interface, which is a factory for StreamEndPoint -and VDev objects.</LI> - -<LI> -Implemented a mpeg-1 streaming audio/video application using the a/v service.</LI> -</UL> -Work in progress: -<UL> -<LI> -Implementing the SFP protocol</LI> - -<LI> -Integrating the mpeg-1 streaming application with the trading service.</LI> -</UL> - -<HR> -<H3> -<A NAME="apps"></A>Test & Example Applications</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>Future work: - -<P>Developing a one-buttoned test for all the different TAO tests similar -to the ACE-one buttoned test. - -<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> - -<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> -Point of contact: <A HREF="mailto:mk1@cec.wustl.edu">Michael Kircher</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_and_LifeCycleService.ps.gz">online</A>. -This discussion focuses on the following goals:<P> - -<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> - -<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> -<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> -<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> -<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 61220111426..00000000000 --- a/TAO/docs/releasenotes/orbcore.html +++ /dev/null @@ -1,503 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> - -<!-- $Id$ --> - -<html> - <head> - <title>ORB Core Status</title> - </head> - -<BODY TEXT="#000000" BGCOLOR="#FFFFFF"> - <H3><A NAME="orb"></A>ORB & ORB Core</H3> Point of - contact: <A HREF="mailto:nanbor@cs.wustl.edu">Nanbor Wang</A> - - <p>Last Update: $Date$ </P> - -<P> -<b>Current status:</b> - -<UL> - <LI>Provides dynamically linked wholesale assignment of ORB - strategies for communication, concurrency, demultiplexing, - scheduling, and dispatching using the ACE Service Configurator - framework.</LI> - - <LI>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>.)</LI> - - <LI>Supports <TT>resolve_initial_references("NameService")</TT> - using ACE support for multicast.</LI> -</UL><p> - -<b>Known issues:</b> -<UL> - <li>Some CORBA objects need to have access to the ORB. We tend to - use TAO_ORB_Core_instance ()->orb () to fetch the right ORB the - object is using. This is most often true when implementing the - shutdown method which allow other process to shutdown a remote - ORB. Althought this may be the "right" thing to do in TAO, it - is not CORBA compliant and hurts the portability of object - implementation. - - A common way of getting around this problem is to cache the ORB - pointer in the object when it is created and simply use the - cached ORB when needed. However, remember that there could be - multiple ORBs in a process and a POA may be shared by several - ORBs. That means, we may not handling the object with the same - ORB it was created. Collocation optimization further complicated - the problem. - - At the moment, using TAO_ORB_Core_instance ()->orb () is the - only sane way to get arond the problem. Though there may be a - better way.<p> - - <li>The acceptor on the server side doesn't get opened until calling - CORBA_ORB::run (). And that's when we check whether the port - the server wants to listen on is available or not. (Unless we - specify ORBport to be 0, which implicitly ask the ORB to open - the connection in ORB_init so we know how to export object - IORs.) The problem of this approach is that the port the server - is listen on may not be available. Since we export object IORs - based on the port specified (or the default port,) without - checking the availability of the port, we may announce a bad IOR - end-point which the server will never be able to listen on. - - A possible solution might be opening the server acceptor - whenever it is trying to export an IOR.<p> - - <li>The ORB doesn't handle the nested upcalls correctly. This seems - to be stemmed from the incorrect suspension/resumption of file - descriptor in connection management. It appears to work fine - when two client and server calling each other from invoking an - object method. This, however, is broken when a third ORB - makes use of the object exported by the original client when the - nested upcalls are in progress.<p> - - <LI>The current demarshalling scheme may not work in cases of - complex types such as sequences of unions or anys or object - references. The engine has difficulty determining the dynamic - type of the objects.<p> - - <LI>Object references for objects dynamically created within - a server may not have proper host.</em> (See also <a - href="#hostfix">recent fix</a>.) - 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.<br> - - However, if there are multiple interfaces on a machine - <i>and</i> 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#-ORBhost"><b>-ORBhost</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> -</Ul> - -<b>Recently Completed Work:</b> - -<UL> - <li>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. - - <li>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. - - <li>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 <code>-ORBport 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 <code>-ORBport 0</code> is issued so it can get the - actual address to publish the IOR for clients' use. - - <li>Added optimization for collocated objects. This - optimization enables TAO to bypass communication layers and - talks to collocated objects directly.</li> - - <li>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.</li> - - <li>Eliminated substantial memory leaks in servers.</li> - - <li>Added documentation for <a - href="../Options.html#-ORBpoa"><b>-ORBpoa</b></a>, which - allows individual tweaking of the POA's locality (global - vs. thread-specific) independent of the locality of other - ORB resources. Also, <a - href="../Options.html#-ORBpoalock"><b>-ORBpoalock</b></a> - and <a - href="../Options.html#-ORBpoamgrlock"><b>-ORBpoamgrlock</b></a> - control locking in the POA and POA manager, respectively, - according to application needs.</li> - - <li>Began the process of changing the internals of TAO to use - the "underbar" namespace mapping. This should be completed - soon.</li> - - <li>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.</li> - - <li><code>CORBA_ORB::run()</code> should be able to be called - multiply in the same execution path now.</li> - - <li>Fixed the <b>LOCATION_FORWARD</b> capabilities to work as - described in the CORBA 2.1 and the POA specification.</li> - - <li>Fixed problem in the IDL Cubit example which caused the - server to dump core when dealing with <code>_out</code> sequence - types <em>ONLY</em> when compiled with G++. It seems that G++ - decided to interpret the expression <code>output == 0</code> - (where <code>output</code> is of type <code>vector_out</code>) - differently from Sun's C++ compiler.</li> - - <li>Fixed a slight problem in <a href="#hostfix">other recent - work</a> where a servant listening on <code>INADDR_ANY</code> - reported an IOR with address <tt>0.0.0.0</tt>. It now reports - the default hostname instead.</li> - - <LI>Working version of TAO on VxWorks with VME transport.</li> - - <li>TAO now reacts gracefully in the face of a non-existent - <code>svc.conf</code> file or simply missing entries in the - file. It logs a warning message and uses default values - versions of items which it would normally obtain from the - Service Repository.</li> - - <li><a name="hostfix"></a>Fixed problem where object references - for objects dynamically created within a server do not have - proper host, at least if the desired host was specified using <a - href="../Options.html#-ORBhost"><b>-ORBhost</b></a> on the - command line.</li> - - <li>Added support for <a - href="../Options.html#-ORBsndsock"><b>-ORBsndsock</b></a> and <a - href="../Options.html#-ORBrcvsock"><b>-ORBrcvsock</b></a> ORB - options. See <a href="../Options.html">options - documentation</a> for details.</li> - - <li>Added support for pre-established connections using the <a - href="../Options.html#-ORBpreconnect"><b>-ORBpreconnect</b></a> - option. This allows connections to be esablished before any - CORBA requests are made. See <a href="../Options.html">options - documentation</a> for details.</li> - - <li>Eliminated deprecated <b>-OAxxx</b> options parsed by the - Object Adapter <code>init</code> method but no longer used by - part of the ORB.</li> - - <li>Made argument parsing within the ORB and POA consume the - arguments it parses.</li> - - <li>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.</li> - - <li>Got rid of need to have compile in TSS ORB Core - (<code>-DTAO_HAS_TSS_ORBCORE</code>). This is accomplished by - having a Resource Factory (<code>TAO_Resource_Factory</code>) - singleton which the ORB Core consults in order to get pointers - to resources. The Resource Factory can be configured to - return pointers from thread-specific storage, or - process-global storage. By doing this, the ORB Core is - shielded from ever having to know whether or not its resources - are global or not.</li> - - <li>Made all command-line like options look like the - standard-professed options, i.e., <b>-ORBxxx</b> or - <b>-OAxxxx</b>.</li> - - <li>Moved ORB option parsing into - <code>TAO_ORB_Core::init()</code> rather than in - <code>ORB_init()</code>.</li> - - <li>Define <code>_FAR</code> for all cases as an interim fix - for LynxOS.</li> - - <li>Fixed TAO so that the default port of 5001 is defined in - <code>orb_core.h</code> config header somewhere rather than in - <code>orbobj.cpp</code>, and use <b>MAXHOSTNAMELEN</b> ACE - constant for the hostname buffer.</li> - - <li>Eliminated need for <code>CORBA::Object</code> to keep a - pointer to its orb sitting around anywhere.</li> - - <LI>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.</li> - - <li>Created a brief section in <a - href="../../TAO-INSTALL.html"><code>$TAO_ROOT/TAO-INSTALL.html</code></a> - that <em>briefly</em> documents installation on Unix - platforms. There is also a brief section which documents - issues that apply across ALL platforms, such as the fact that - TAO and its application will likely not work well if your ACE - is linked through Orbix, VisiBroker, or another ORB. <a - href="../../ChangeLog">ChangeLog</a> discovery attribution for - this should go to <em>Steve Wohlever - <wohlever@mitre.org></em>.</li> - - <LI>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.</li> - - <LI>Validated movement of Strategy Connector into - ORB Core.</LI> - - <li>Tested and commited <code>Connector::connect_n</code> - changes to ACE</code>.</li> - - <li>ACE & TAO compiling cleanly using Sun's CC on Solaris and - G++ on Linux. Also, the ACE tests run properly.</li> - - <li>Use <code>truss</code> to verify for <a - href="mailto:PAUL.G.WEHLAGE@cdev.com">Paul Wehlage</a> that - TAO really uses <code>select</code> vs. <code>recv</code> for - <b>-R</b> vs. <b>-T</b>.</li> - - <li>Renamed <code>boa.*</code> to <code>poa.*</code>.</li> - - <LI>Renamed following files: Orb_Core.* ->orb_core.* - & orbobj.* -> corba_orb.*.</LI> - - <LI>The lock used in <code>giop.cpp:626</code> originally - appeared in the IIOP-1.4 code base. Its purpose was to - protect access to the <code>fwd_profile</code> data member. - The original features are available, but they are currently - not used because none of our concurrency models present a - thread-unsafe condition. The <a - href="../../ChangeLog">ChangeLog</a> presents more details - on the subject.</li> - - <li>Fixed problems seen by <a - href="mailto:brian.r.mendel@boeing.com">Brian Mendel</a> of - Boeing where the Cubit server application was crashing in - <code>TAO_OA_Connection_Handler::handle_message</code> when it - was trying to call <code>CORBA::POA::handle_request</code> - through a NULL <code>root_poa</code> pointer. The NULL - pointer resulted from the inadvertent use of the - Thread-per-Connection concurrency model, which is currently - incompatible with the ORB-per-thread model. It was not caught - because the change is normally done in configuration files - parsed by the Service Configurator, and VxWorks requires - special code in that area which was not tested until Boeing - got hold of the code.</li> - - <li>Clean up build under g++. All 'function used before - declared inline' warnings have been eliminated. Also, all - other warnings (except for one that is nearly unavoidable) - have been eliminated. - </li> - - <LI>Removed BOA and ROA names from the ORB.</LI> - - <LI>Changed <code>CORBA_ORB::open()</code> to return an error - status (first cut at this already there--needs to be checked - out).</LI> - - <LI>Added README file to multiCubit test.</li> -</UL><p> - -<b>Ongoing Work:</b> - -<UL> - <LI>Verify ACE & TAO on Linux using g++, Solaris using CC, and - Solaris using g++.</LI> - - <LI>Use Purify to eliminate straggling problems.</LI> - - <LI>Clean up the internals and analyze for performance - bottlenecks using Quantify.</LI> - - <li>Resolve <code>// @@</code> comment blocks. These are - questions or comments placed in the code by a reviewer - (typically Doug).</li> - - <li>Make more and better documentation on the internals of - TAO.</li> -</UL><p> - -<b>Current Work:</b> - -<UL> - <LI> - <p>Verify that, in the ORB-per-thread concurrency model, - it's possible to have a factory in each thread that creates - a client and returns an object reference to that client - within that thread. This is different from the model that - Sumedh originally had where the factory was trying to turn - out a client in a separate thread/ORB combination. - - <p>There is no application which attempts this at the moment, - so both a client and a server will need to be manufactured. - Using existing Cubit-like examples (that poor app is so - weary) should reduce development time to a couple of - hours. - - <p>The real strategy/solution is to make - <code>CORBA::Object</code> not keep a pointer to its orb - sitting around anywhere. It should only get it when it needs - it. This should not be difficult to change. - </LI> -</UL><p> - -<b>Critical Work:</b> - -<UL> - <li>Identify/fix the problems in multithreaded client with TSS - resources. This could be done using the leader-follower model - (thread-pool.) - <LI>Support new concurrency models, e.g., Thread-per-Request, - thread pool, etc..</LI> -</UL> - -<b>Future work:</b> -<UL> - <li>Performance optimizations, such as: - <ol> - <li>Strategize 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 want to be able to "hold" a - service handler for a string of requests. And, of course, - do this in a portable manner.</LI> - - <li>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.</li> - </ol> - </li> - - <li>Robustness improvements: - <ol> - <li>Improve connection cache so that it won't crash when there - are no more slots or sockets.</li> - - <li>Add an option to the ORB core, e.g., - <b>-ORBnameservicetimeout</b>, to allow specification of an - upper bound on the itime-to-wait for a response from the - ORB's multicast "search" for a running name server.</li> - </ol> - </li> - - <li>New features: - <ol> - <li>Implement <code>ORB::perform_work</code> and - <code>ORB::work_pending</code> so that <code>ORB::run</code> - <em>could</em> be implemented in terms of them.</li> - - <li>Improve the <code>Service Configurator</code> service - entry faking on VxWorks.</li> - - <li>Integrate with realtime upcalls (RTUs).</li> - - </ol> - </li> - - <li>Internal restructuring: - <ol> - <li>Remove <code>_FAR</code> from all code.</li> - - <li>Rework underlayment to eliminate <code>IUnknown</code> class.</li> - - <li>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.</li> - - <li>Rethink the entire memory allocation model used by the - ORB. The current one from SSIIOP may no longer be suitable - for our purposes.</li> - </ol> - </li> - - <li>Documentation: - <ol> - <li>Update ORB Patterns paper to reflect the latest TAO has to - offer. Specifically - <ul> - <li>sections on the Abstract Factory and Concurrency - strategies need to be updated, and the entire paper needs to - be reviewed for accuracy w.r.t the current TAO.</li> - <li>Metrics must be re-computed.</li> - <li>Tighten existing discussions.</li> - <li>Add information on new patterns (such as TSS) which - have been used since initial work.</li> - </ul> - - <li>Make the section in <a - href="../../TAO-Install.html"><code>$TAO_ROOT/TAO-Install.html</code></a> - that documents installation on Unix platforms more complete.</li> - - </ol> </li> - - <li>Miscellany: - <ol> - <LI>Assist in porting higher level services (e.g., <A - HREF="#eventchannel">Event Channel</A>) to TAO.</LI> - - <li>Compile and verify ACE and TAO on Linux using the Kuck and - Associates, Inc. (KAI) compiler tools.</li> - <LI>CORBA::TypeCode is causing a memory leak. Since objects - of this type are rather static in nature, this is - currently not a big deal. However, it should be fixed - soon. </LI> - <LI>CORBA_Exception::Release is not working correctly as the - memory is never really freed. </LI> - </ol> - </li> - - - <li>Potential Optimizations: - <ol> - <LI>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. </LI> - </ol> - </li> - - -</UL> - -</body> -</html> diff --git a/TAO/docs/releasenotes/trader.html b/TAO/docs/releasenotes/trader.html deleted file mode 100644 index a0abc7017b5..00000000000 --- a/TAO/docs/releasenotes/trader.html +++ /dev/null @@ -1,1069 +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::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> -</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><strong>Note: </strong>The export_test and the Trading_Service executables are servers ---- the export_test is a server of dynamic properties. Hence, if you run both executables -on the same machine, you must supply them with different ports. For example, add -ORBport -0 to the export_test command line. </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>The following is a list of known problems with TAO that adversly affect the Trading -Service, and the workarounds applied to those problems.</p> - -<p><strong>Problem: </strong>TAO has difficulty marshalling and demarshalling object -references that extend <tt>CORBA::Object</tt> when they occur as a field in a <tt>struct</tt>. -In the CosTrading IDL file there are two <tt>structs</tt> passed that contain such object -references: <tt>CosTradingDynamic::DynamicProp</tt> and <tt>CosTrading::Link:LinkInfo</tt>. -<br> -<strong>Workaround</strong>: Instead of passing object references in the structs, we pass -the IORs of those object references, strings. The IDL file and the Trading Service code is -compiled with the preprocessor flag <tt>TAO_HAS_OBJECT_IN_STRUCT_MARSHAL_BUG</tt>. For -dynamic properties, as long as the trader clients use the <tt>TAO_Property_Evaluator</tt> -and <tt>TAO_Dynamic_Property</tt> classes, this workaround will be invisible --- these -classes hide the use of the <tt>DynamicProp struct</tt>. However, for those applications -that invoke the <tt>CosTrading::Link::describe_link</tt> method, checking for that flag -definition will be necessary. Two additional lines of code will suffice--- a call to <tt>CORBA::ORB::string_to_object</tt>, -and either <tt>CosTrading::Lookup::_narrow</tt> or <tt>CosTrading::Register::_narrow</tt> -depending on the field of LinkInfo.</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> |