The R13B03 release.OTP_R13B03

1 files changed, 182 insertions, 0 deletions

diff --git a/lib/ic/internal_doc/protocol.txt b/lib/ic/internal_doc/protocol.txt
new file mode 100644
index 0000000000..54e1ef55cf
--- /dev/null
+++ b/lib/ic/internal_doc/protocol.txt
@@ -0,0 +1,182 @@
+Peter Hogfeldt			2003-08-18	PA3
+
+THE IC PROTOCOL
+
+1   INTRODUCTION
+
+    The IDL Compiler (IC) transforms Interface Definition Language
+    (IDL) specifications files to interface code for Erlang, C, and
+    Java. The Erlang language mapping is described in the Orber
+    documentation, while the other mappings are described in the IC
+    documentation (they are of course in accordance with the CORBA C
+    and Java language mapping specifications, with some restrictions).
+
+    The most important parts of an IDL specification are the operation
+    declarations. An operation defines what information a client
+    provides to a server, and what information (if any) the client
+    gets back from the server. We consider IDL operations and language
+    mappings in section 2.
+
+    What we here call the IC protocol, is the description of messages
+    exchanged between IC end-points (client and servers). It is valid
+    for all IC back-ends, except the 'erl_plain' and 'erl_corba'
+    back-ends. The protocol is described in section 3.
+
+    The IC protocol is in turn embedded into the Erlang gen_server
+    protocol, which is described in section 4.
+
+    Finally, the gen_server protocol is embedded in the Erlang
+    distribution protocol. Pertinent parts of that protocol is
+    described in section 5.
+
+
+2   LANGUAGE MAPPINGS AND IDL OPERATIONS
+
+2.1 IDL Operations
+
+    An IDL operation is declared as follows:
+
+    [oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN,
+	     out OType1 O1, out OType2 O2, ..., out OTypeM OM)
+				N, M = 0, 1, 2, ...		(2.1.1)
+
+    `Op' is the operation name, RetType is the return type, and ITypei, 
+    i = 1, 2, ..., N, and OTypej, j = 1, 2, ..., M, are the `in' types
+    and `out' types, respectively. The values I1, I2, ..., IN are 
+    provided by the caller, and the value of RetType, and the values
+    O1, O2, ..., OM, are provided as results to the caller. 
+
+    The types can be any basic types or derived types declared in the
+    IDL specification of which the operation declaration is a part.
+
+    If the RetType has the special name `void' there is no return
+    value (but there might still be result values O1, 02, ..., OM).
+
+    The `in' and `out' parameters can be declared in any order, but
+    for clarity we have listed all `in' parameters before the `out'
+    parameters in the declaration above.
+
+    If the keyword `oneway' is present, the operation is a cast, i.e.
+    there is no confirmation of the operation, and consequently there
+    must be no result values: RetType must be equal to `void', and M =
+    0 must hold.
+
+    Otherwise the operation is a call, i.e. it is confirmed (or else
+    an exception is raised). 
+
+    Note carefully that an operation declared without `oneway' is
+    always a call, even if RetType is `void' and M = 0.
+
+2.2 Language Mappings
+
+    There are several CORBA Language Mapping specifications. These are
+    about mapping interfaces to various programming languages. IC
+    supports the CORBA C and Java mapping specifications, and the
+    Erlang language mapping specified in the Orber documentation. 
+
+    Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide:
+
+        Functions with return type void will return the atom ok.
+
+    Excerpt from "6.13 Invocations of Operations" in the Orber User's Guide:
+
+        A function call will invoke an operation. The first parameter
+        of the function should be the object reference and then all in
+        and inout parameters follow in the same order as specified in
+        the IDL specification. The result will be a return value
+        unless the function has inout or out parameters specified; in
+        which case, a tuple of the return value, followed by the
+        parameters will be returned.
+
+    Hence the function that is mapped from an IDL operation to Erlang
+    always have a return value (an Erlang function always has). That
+    fact has influenced the IC protocol, in that there is always a
+    return value (which is 'ok' if the return type was declared 'void'). 
+
+
+3   IC PROTOCOL
+
+    Given the operation declaration (2.1.1) the IC protocol maps to
+    messages as follows, defined in terms of Erlang terms.
+
+3.1 Call (Request/Reply, i.e. not oneway)
+
+    request:		 Op			atom()		N = 0	
+			 {Op, I1, I2, ..., IN}	tuple()		N > 0
+								(3.1.1)
+
+    reply:		 Ret					M = 0
+			 {Ret, O1, O2, ..., OM}			M > 0
+								(3.1.2)
+
+    Notice; Even if the RetType of the operation Op is declared to be
+    'void', a return value 'ok' is returned in the reply message. That
+    return value is of no significance, and is therefore ignored (note
+    however that a C server back-end returns the atom 'void' instead
+    of 'ok'). 
+
+3.2 Cast (oneway)
+
+    notification:	Op			atom()		N = 0
+			{Op, I1, I2, ..., IN}	tuple()		N > 0
+								(3.2.1)
+    (There is of course no return message).
+
+3.3 Propagation of Exceptions
+
+    Currently there is no propagation of exceptions from the server to
+    the client. As it is now a an exception detected by the server
+    will hang the client in a receive. That is unacceptable.
+
+    Exception propagation is only meaningful for Call (request/reply).
+
+
+4   GEN_SERVER PROTOCOL
+
+    Most of the IC generated code deals with encoding and decoding the
+    gen_server protocol. 
+
+4.1 Call
+
+    request:	{'$gen_call', {self(), Ref}, Request}		(4.1.1)
+
+    reply:	{Ref, Reply}					(4.1.2)
+
+    where Request and Reply are the messages defined in 3.1 Call. 
+
+4.2 Cast
+
+    notification:    {'$gen_cast', Notification}		(4.2.1)
+
+    where Notification is the message defined in 3.2 Cast. 
+
+
+5   ERLANG DISTRIBUTION PROTOCOL
+
+    Messages (of interest here) between Erlang nodes are of the form: 
+
+        Len(4), Type(1), CtrlBin(N), MsgBin(M)			(5.1)
+
+    Type is equal to 112 = PASS_THROUGH. 
+
+    CtrlBin and MsgBin are Erlang terms in binary form (as if created
+    by term_to_binary/1), whence for each of them the first byte is
+    equal to 131 = VERSION_MAGIC.
+
+    CtrlBin (of interest here) contains the SEND and REG_SEND control
+    messages, which are binary forms of the Erlang terms
+
+	{2, Cookie, ToPid} ,					(5.2)
+
+    and
+
+	{6, FromPid, Cookie, ToName} ,				(5.3)
+
+    respectively.
+
+    The CtrlBin(N) message is read and written by erl_interface code
+    (C), j_interface code (Java), or the Erlang distribution
+    implementation, which are invoked from IC generated code. 
+
+    The MsgBin(N) is the "real" message, i.e. of the form described
+    in section 4.