summaryrefslogtreecommitdiff
path: root/TAO/docs/DIFFERENCES
diff options
context:
space:
mode:
Diffstat (limited to 'TAO/docs/DIFFERENCES')
-rw-r--r--TAO/docs/DIFFERENCES360
1 files changed, 0 insertions, 360 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.