<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- IC Protocol</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/ic-4.2.31.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>ic</strong><br><strong>User's Guide</strong><br><small>Version 4.2.31</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Using the IC Compiler" expanded="false">Using the IC Compiler<ul>
<li><a href="ch_introduction.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_introduction.html#id62832">Introduction</a></li>
<li title="Compilation of IDL Files"><a href="ch_introduction.html#id60118">Compilation of IDL Files</a></li>
</ul>
</li>
<li id="no" title="OMG IDL" expanded="false">OMG IDL<ul>
<li><a href="ch_basic_idl.html">
Top of chapter
</a></li>
<li title="OMG IDL - Overview"><a href="ch_basic_idl.html#id61149">OMG IDL - Overview</a></li>
</ul>
</li>
<li id="loadscrollpos" title="IC Protocol" expanded="true">IC Protocol<ul>
<li><a href="ch_ic_protocol.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_ic_protocol.html#id66622">Introduction</a></li>
<li title="Language mappings and IDL operations"><a href="ch_ic_protocol.html#id63114">Language mappings and IDL operations</a></li>
<li title="IC Protocol"><a href="ch_ic_protocol.html#id64104">IC Protocol</a></li>
<li title="Gen_server Protocol"><a href="ch_ic_protocol.html#id65537">Gen_server Protocol</a></li>
<li title="Erlang Distribution Protocol"><a href="ch_ic_protocol.html#id65584">Erlang Distribution Protocol</a></li>
</ul>
</li>
<li id="no" title="Using the Plain Erlang Back-end" expanded="false">Using the Plain Erlang Back-end<ul>
<li><a href="ch_erl_plain.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_plain.html#id63664">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_plain.html#id63678">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_plain.html#id63697">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_plain.html#id63754">An Example</a></li>
</ul>
</li>
<li id="no" title="Using the Erlang Generic Server Back-end" expanded="false">Using the Erlang Generic Server Back-end<ul>
<li><a href="ch_erl_genserver.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_genserver.html#id63935">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_genserver.html#id63953">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_genserver.html#id63977">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_genserver.html#id69038">An Example</a></li>
</ul>
</li>
<li id="no" title="IDL to C mapping" expanded="false">IDL to C mapping<ul>
<li><a href="ch_c_mapping.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_mapping.html#id69337">Introduction</a></li>
<li title="C Mapping Characteristics"><a href="ch_c_mapping.html#id69440">C Mapping Characteristics</a></li>
<li title="Basic OMG IDL Types"><a href="ch_c_mapping.html#id69638">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_c_mapping.html#id70147">Constructed OMG IDL Types</a></li>
<li title="OMG IDL Constants"><a href="ch_c_mapping.html#id71595">OMG IDL Constants</a></li>
<li title="OMG IDL Operations"><a href="ch_c_mapping.html#id71622">OMG IDL Operations</a></li>
<li title="Exceptions"><a href="ch_c_mapping.html#id71884">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_c_mapping.html#id71897">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for the C-client"><a href="ch_c_mapping.html#id71908">Summary of Argument/Result Passing for the C-client</a></li>
<li title="Supported Memory Allocation Functions"><a href="ch_c_mapping.html#id73513">Supported Memory Allocation Functions</a></li>
<li title="Special Memory Deallocation Functions"><a href="ch_c_mapping.html#id73642">Special Memory Deallocation Functions</a></li>
<li title="Exception Access Functions"><a href="ch_c_mapping.html#id73681">Exception Access Functions</a></li>
<li title="Special Types"><a href="ch_c_mapping.html#id73720">Special Types</a></li>
<li title="A Mapping Example"><a href="ch_c_mapping.html#id73844">A Mapping Example</a></li>
</ul>
</li>
<li id="no" title="The C Client Back-end" expanded="false">The C Client Back-end<ul>
<li><a href="ch_c_client.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_client.html#id73982">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_client.html#id74007">Generated Stub Files</a></li>
<li title="C Interface Functions"><a href="ch_c_client.html#id74057">C Interface Functions</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_client.html#id74134">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_client.html#id74198">An Example</a></li>
</ul>
</li>
<li id="no" title="The C Server Back-end" expanded="false">The C Server Back-end<ul>
<li><a href="ch_c_server.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_server.html#id74326">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_server.html#id74352">Generated Stub Files</a></li>
<li title="C Skeleton Functions"><a href="ch_c_server.html#id74402">C Skeleton Functions</a></li>
<li title="The Server Loop"><a href="ch_c_server.html#id74461">The Server Loop</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_server.html#id74488">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_server.html#id74553">An Example</a></li>
</ul>
</li>
<li id="no" title="CORBA_Environment C Structure" expanded="false">CORBA_Environment C Structure<ul>
<li><a href="ch_c_corba_env.html">
Top of chapter
</a></li>
<li title="C Structure"><a href="ch_c_corba_env.html#id74686">C Structure</a></li>
<li title="The CORBA Compatibility Part"><a href="ch_c_corba_env.html#id74758">The CORBA Compatibility Part</a></li>
<li title="The External Part"><a href="ch_c_corba_env.html#id74811">The External Part</a></li>
<li title="The Internal Part"><a href="ch_c_corba_env.html#id74944">The Internal Part</a></li>
<li title="Creating and Initiating the CORBA_Environment Structure"><a href="ch_c_corba_env.html#id75066">Creating and Initiating the CORBA_Environment Structure</a></li>
<li title="Setting System Exceptions"><a href="ch_c_corba_env.html#id75376">Setting System Exceptions</a></li>
</ul>
</li>
<li id="no" title="IDL to Java language Mapping" expanded="false">IDL to Java language Mapping<ul>
<li><a href="ch_java.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_java.html#id75488">Introduction</a></li>
<li title="Specialties in the Mapping"><a href="ch_java.html#id75549">Specialties in the Mapping</a></li>
<li title="Basic OMG IDL Types"><a href="ch_java.html#id75576">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_java.html#id75983">Constructed OMG IDL Types</a></li>
<li title="Mapping for Constants"><a href="ch_java.html#id76049">Mapping for Constants</a></li>
<li title="Invocations of Operations"><a href="ch_java.html#id76060">Invocations of Operations</a></li>
<li title="Exceptions"><a href="ch_java.html#id76110">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_java.html#id76123">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for Java"><a href="ch_java.html#id76134">Summary of Argument/Result Passing for Java</a></li>
<li title="Communication Toolbox"><a href="ch_java.html#id76192">Communication Toolbox</a></li>
<li title="The Package com.ericsson.otp.ic"><a href="ch_java.html#id76492">The Package com.ericsson.otp.ic</a></li>
<li title="The Term Class"><a href="ch_java.html#id76892">The Term Class</a></li>
<li title="Stub File Types"><a href="ch_java.html#id77170">Stub File Types</a></li>
<li title="Client Stub Initialization, Methods Exported"><a href="ch_java.html#id77234">Client Stub Initialization, Methods Exported</a></li>
<li title="Server Skeleton Initialization, Server Stub Implementation, Methods Exported"><a href="ch_java.html#id77415">Server Skeleton Initialization, Server Stub Implementation, Methods Exported</a></li>
<li title="A Mapping Example"><a href="ch_java.html#id77546">A Mapping Example</a></li>
<li title="Running the Compiled Code"><a href="ch_java.html#id77630">Running the Compiled Code</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>3 IC Protocol</h1>
<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>
<h3><a name="id66622">3.1
Introduction</a></h3>
<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>
<h3><a name="id63114">3.2
Language mappings and IDL operations</a></h3>
<h4>IDL Operations</h4>
<p>An IDL operation is declared as follows:</p>
<div class="example"><pre>
[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)
</pre></div>
<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>
<h4>Language Mappings</h4>
<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>
<ul>
<li>
<p>Functions with return type void will return the atom ok.</p>
</li>
</ul>
<p>Excerpt from "6.13 Invocations of Operations" in the Orber User's
Guide:
</p>
<ul>
<li>
<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>
</li>
</ul>
<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>
<h3><a name="id64104">3.3
IC Protocol</a></h3>
<p>Given the operation declaration (2.1.1) the IC protocol maps to
messages as follows, defined in terms of Erlang terms.
</p>
<h4>Call (Request/Reply, i.e. not oneway)</h4>
<div class="example"><pre>
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)</pre></div>
<p><strong>Notice:</strong> 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>
<h4>Cast (oneway)</h4>
<div class="example"><pre>
notification: Op atom() N = 0
{Op, I1, I2, ..., IN} tuple() N > 0
(3.2.1)</pre></div>
<p>(There is of course no return message).
</p>
<h3><a name="id65537">3.4
Gen_server Protocol</a></h3>
<p>Most of the IC generated code deals with encoding and decoding the
gen_server protocol.
</p>
<h4>Call</h4>
<div class="example"><pre>
request: {'$gen_call', {self(), Ref}, Request} (4.1.1)
reply: {Ref, Reply} (4.1.2)</pre></div>
<p>where Request and Reply are the messages defined in the previous
chapter.
</p>
<h4>Cast</h4>
<div class="example"><pre>
notification: {'$gen_cast', Notification} (4.2.1) </pre></div>
<p>where Notification is the message defined in the previous chapter.
</p>
<h3><a name="id65584">3.5
Erlang Distribution Protocol</a></h3>
<p>Messages (of interest here) between Erlang nodes are of the form: </p>
<div class="example"><pre>
Len(4), Type(1), CtrlBin(N), MsgBin(M) (5.1) </pre></div>
<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>
<div class="example"><pre>
{2, Cookie, ToPid} , (5.2) </pre></div>
<p>and</p>
<div class="example"><pre>
{6, FromPid, Cookie, ToName} , (5.3) </pre></div>
<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>
</div>
<div class="footer">
<hr>
<p>Copyright © 1998-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
709
