diff options
Diffstat (limited to 'lib/ic/doc/src/ch_ic_protocol.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_ic_protocol.xml | 233 |
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> + |