The R13B03 release.OTP_R13B03

1 files changed, 233 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ch_ic_protocol.xml b/lib/ic/doc/src/ch_ic_protocol.xml
new file mode 100644
index 0000000000..678fdc766c
--- /dev/null
+++ b/lib/ic/doc/src/ch_ic_protocol.xml
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2003</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>IC Protocol</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>2003-12-11</date>
+    <rev>PA1</rev>
+    <file>ch_ic_protocol.xml</file>
+  </header>
+  <p>The purpose of this chapter is to explain the bits and bytes of the
+    IC protocol, which is a composition of the Erlang distribution protocol
+    and the Erlang/OTP gen_server protocol. If you do not intend to replace
+    the Erlang distribution protocol, or replace the gen_server protocol, 
+    skip over this chapter. 
+    </p>
+
+  <section>
+    <title>Introduction</title>
+    <p>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).
+      </p>
+    <p>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.
+      </p>
+    <p>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 IC protocol is in turn embedded into the Erlang gen_server
+      protocol, which is described below.
+      Finally, the gen_server protocol is embedded in the Erlang
+      distribution protocol. Pertinent parts of that protocol is
+      described further below.
+      </p>
+  </section>
+
+  <section>
+    <title>Language mappings and IDL operations</title>
+
+    <section>
+      <title>IDL Operations</title>
+      <p>An IDL operation is declared as follows:</p>
+      <code type="none">
+\011[oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN,
+\011out OType1 O1, out OType2 O2, ..., out OTypeM OM)
+\011N, M = 0, 1, 2, ...\011\011(2.1.1)
+      </code>
+      <p>`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. 
+        </p>
+      <p>The types can be any basic types or derived types declared in the
+        IDL specification of which the operation declaration is a part.
+        </p>
+      <p>If the RetType has the special name `void' there is no return
+        value (but there might still be result values O1, 02, ..., OM).
+        </p>
+      <p>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.
+        </p>
+      <p>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.
+        </p>
+      <p>Otherwise the operation is a call, i.e. it is confirmed (or else
+        an exception is raised). 
+        </p>
+      <p>Note carefully that an operation declared without `oneway' is
+        always a call, even if RetType is `void' and M = 0.
+        </p>
+    </section>
+
+    <section>
+      <title>Language Mappings</title>
+      <p>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. 
+        </p>
+      <p>Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide:
+        </p>
+      <list type="bulleted">
+        <item>
+          <p>Functions with return type void will return the atom ok.</p>
+        </item>
+      </list>
+      <p>Excerpt from "6.13 Invocations of Operations" in the Orber User's 
+        Guide:
+        </p>
+      <list type="bulleted">
+        <item>
+          <p>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.</p>
+        </item>
+      </list>
+      <p>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'). </p>
+    </section>
+  </section>
+
+  <section>
+    <title>IC Protocol</title>
+    <p>Given the operation declaration (2.1.1) the IC protocol maps to
+      messages as follows, defined in terms of Erlang terms.
+      </p>
+
+    <section>
+      <title>Call (Request/Reply, i.e. not oneway)</title>
+      <code type="none">
+    request:\011\011 Op\011\011\011atom()\011\011N = 0\011
+\011\011\011 {Op, I1, I2, ..., IN}\011tuple()\011\011N > 0
+\011\011\011\011\011\011\011\011(3.1.1)
+
+    reply:\011\011 Ret\011\011\011\011\011M = 0
+\011\011\011 {Ret, O1, O2, ..., OM}\011\011\011M > 0
+\011\011\011\011\011\011\011\011(3.1.2)      </code>
+      <p><em>Notice:</em> 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'). 
+        </p>
+    </section>
+
+    <section>
+      <title>Cast (oneway)</title>
+      <code type="none">
+
+    notification:\011Op\011\011\011atom()\011\011N = 0
+\011\011\011{Op, I1, I2, ..., IN}\011tuple()\011\011N > 0
+\011\011\011\011\011\011\011\011(3.2.1)      </code>
+      <p>(There is of course no return message).
+        </p>
+    </section>
+  </section>
+
+  <section>
+    <title>Gen_server Protocol</title>
+    <p>Most of the IC generated code deals with encoding and decoding the
+      gen_server protocol. 
+      </p>
+
+    <section>
+      <title>Call</title>
+      <code type="none">
+
+    request:\011{'$gen_call', {self(), Ref}, Request}\011\011(4.1.1)
+
+    reply:\011{Ref, Reply}\011\011\011\011\011(4.1.2)      </code>
+      <p>where Request and Reply are the messages defined in the previous
+        chapter.
+        </p>
+    </section>
+
+    <section>
+      <title>Cast</title>
+      <code type="none">
+    notification:    {'$gen_cast', Notification}\011\011(4.2.1)      </code>
+      <p>where Notification is the message defined in the previous chapter.
+        </p>
+    </section>
+  </section>
+
+  <section>
+    <title>Erlang Distribution Protocol</title>
+    <p>Messages (of interest here) between Erlang nodes are of the form: </p>
+    <code type="none">
+        Len(4), Type(1), CtrlBin(N), MsgBin(M)\011\011\011(5.1)    </code>
+    <p>Type is equal to 112 = PASS_THROUGH. 
+      </p>
+    <p>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.
+      </p>
+    <p>CtrlBin (of interest here) contains the SEND and REG_SEND control
+      messages, which are binary forms of the Erlang terms</p>
+    <code type="none">
+\011{2, Cookie, ToPid} ,\011\011\011\011\011(5.2)    </code>
+    <p>and</p>
+    <code type="none">
+\011{6, FromPid, Cookie, ToName} ,\011\011\011\011(5.3)    </code>
+    <p>respectively.
+      </p>
+    <p>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. 
+      </p>
+    <p>The MsgBin(N) is the "real" message, i.e. of the form described
+      in the previous section.
+      </p>
+  </section>
+</chapter>
+