diff options
Diffstat (limited to 'lib/ic/doc/src/ch_ic_protocol.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_ic_protocol.xml | 234 |
1 files changed, 0 insertions, 234 deletions
diff --git a/lib/ic/doc/src/ch_ic_protocol.xml b/lib/ic/doc/src/ch_ic_protocol.xml deleted file mode 100644 index cb64500f6e..0000000000 --- a/lib/ic/doc/src/ch_ic_protocol.xml +++ /dev/null @@ -1,234 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2003</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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"> - [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) - </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: 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)</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: Op atom() N = 0 - {Op, I1, I2, ..., IN} tuple() N > 0 - (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: {'$gen_call', {self(), Ref}, Request} (4.1.1) - - reply: {Ref, Reply} (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} (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) (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"> - {2, Cookie, ToPid} , (5.2) </code> - <p>and</p> - <code type="none"> - {6, FromPid, Cookie, ToName} , (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> - |