aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ch_ic_protocol.xml
diff options
context:
space:
mode:
authorLars Thorsen <[email protected]>2018-04-25 15:09:14 +0200
committerLars Thorsen <[email protected]>2018-04-27 12:05:30 +0200
commit6bcdad20c24457393c0d9eeb385d0ff5aa872cd0 (patch)
tree63162ddfa38d92eaff2193b73277aba18160308c /lib/ic/doc/src/ch_ic_protocol.xml
parent87b06e4ab91729f7415578c8ac0aacec28720ad9 (diff)
downloadotp-6bcdad20c24457393c0d9eeb385d0ff5aa872cd0.tar.gz
otp-6bcdad20c24457393c0d9eeb385d0ff5aa872cd0.tar.bz2
otp-6bcdad20c24457393c0d9eeb385d0ff5aa872cd0.zip
Move the corba applcations to separate repository
All corba applications are moved to a separate repository. E.g. orber, ic, cosEvent, cosEventDomain, cosNotifications cosTime, cosTransactions, cosProperty and cosFileTransfer.
Diffstat (limited to 'lib/ic/doc/src/ch_ic_protocol.xml')
-rw-r--r--lib/ic/doc/src/ch_ic_protocol.xml234
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>
-