aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ch_c_server.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/ic/doc/src/ch_c_server.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/ic/doc/src/ch_c_server.xml')
-rw-r--r--lib/ic/doc/src/ch_c_server.xml148
1 files changed, 148 insertions, 0 deletions
diff --git a/lib/ic/doc/src/ch_c_server.xml b/lib/ic/doc/src/ch_c_server.xml
new file mode 100644
index 0000000000..c66ae85fa3
--- /dev/null
+++ b/lib/ic/doc/src/ch_c_server.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1998</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>The C Server Back-end</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date>2004-01-14</date>
+ <rev>C</rev>
+ <file>ch_c_server.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+ <p>With the option <c>{be, c_server}</c> the IDL Compiler generates
+ C server skeletons according to the IDL to C mapping, on top of
+ the Erlang distribution and gen_server protocols.</p>
+ <p>The developer has to write additional code, that together with
+ the generated C server skeletons, form a hidden Erlang
+ node. That additional code contains implementations of call-back
+ functions that implement the true server functionality, and also
+ code uses <c>erl_interface</c> functions for defining the hidden
+ node and for establishing connections to other Erlang nodes.</p>
+ </section>
+
+ <section>
+ <title>Generated Stub Files</title>
+ <p>The generated stub files are:</p>
+ <list type="bulleted">
+ <item>
+ <p>For each IDL interface, a C source file, the name of which
+ is <c><![CDATA[<Scoped Interface Name>__s.c]]></c>. Each operation of the
+ IDL interface is mapped to a C function (with scoped name)
+ in that file;</p>
+ </item>
+ <item>
+ <p>C source files that contain functions for type conversion,
+ memory allocation, and data encoding/decoding;</p>
+ </item>
+ <item>
+ <p>C header files that contain function prototypes and type
+ definitions.</p>
+ </item>
+ </list>
+ <p>All C functions are exported (i.e. not declared static).</p>
+ </section>
+
+ <section>
+ <title>C Skeleton Functions</title>
+ <p>For each IDL operation a C skeleton function is generated, the
+ prototype of which is <c><![CDATA[int <Scoped Function Name>__exec(<Interface Object> oe_obj, CORBA_Environment *oe_env)]]></c>, where <c><![CDATA[<Interface Object>]]></c>, and
+ <c>CORBA_Environment</c> are of the same type as for the
+ generated C client stubs code.</p>
+ <p>Each <c><![CDATA[<Scoped Function Name>__exec()]]></c> function calls the
+ call-back function</p>
+ <p><c><![CDATA[<Scoped Function Name>_rs* <Scoped Function Name>__cb(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env)]]></c></p>
+ <p>where the arguments are of the same type as those generated for
+ C client stubs. </p>
+ <p>The return value <c><![CDATA[<Scoped Function Name>_rs* ]]></c> is a pointer
+ to a function with the same signature as the call-back function
+ <c><![CDATA[<Scoped Function Name>_cb]]></c>, and is called after the call-back
+ function has been evaluated (provided that the pointer is not equal
+ to <c>NULL</c>). </p>
+ </section>
+
+ <section>
+ <title>The Server Loop</title>
+ <p>The developer has to implement code for establishing connections
+ with other Erlang nodes, code for call-back functions and restore
+ functions. </p>
+ <p></p>
+ <p>In addition, the developer also has to implement code for a
+ server loop, that receives messages and calls the relevant
+ <c>__exec</c> function. For that purpose the IC library function
+ <c>oe_server_receive()</c> function can be used.</p>
+ </section>
+
+ <section>
+ <title>Generating, Compiling and Linking</title>
+ <p>To generate the C server skeletons type the following in an
+ appropriate shell:</p>
+ <p><c>erlc -I ICROOT/include "+{be, c_server}" File.idl</c>,</p>
+ <p>where <c>ICROOT</c> is the root of the IC application. The
+ <c>-I ICROOT/include</c> is only needed if <c>File.idl</c>
+ refers to <c>erlang.idl</c>.</p>
+ <p>When compiling a generated C skeleton file, the directories
+ <c>ICROOT/include</c> and <c>EICROOT/include</c>, have to be
+ specified as include directories, where <c>EIROOT</c> is the
+ root directory of the Erl_interface application.</p>
+ <p>When linking object files the <c>EIROOT/lib</c> and
+ <c>ICROOT/priv/lib</c> directories have to be specified. </p>
+ </section>
+
+ <section>
+ <title>An Example</title>
+ <p>In this example the IDL specification file "random.idl" is used
+ for generating C server skeletons (the file is contained in the IC
+ <c>/examples/c-server</c> directory):</p>
+ <code type="none">
+module rmod {
+
+ interface random {
+
+ double produce();
+
+ oneway void init(in long seed1, in long seed2, in long seed3);
+
+ };
+
+}; </code>
+ <p>Generate the C server skeletons:</p>
+ <code type="none">
+erlc '+{be, c_server}' random.idl
+Erlang IDL compiler version X.Y.Z </code>
+ <p>Six files are generated. </p>
+ <p>Compile the C server skeletons:</p>
+ <p>Please read the <c>ReadMe</c> file in the
+ <c>examples/c-server</c> directory.</p>
+ <p>In the same directory you can find all the code for this
+ example. In particular you will find the <c>server.c</c> file
+ that contains all the additional code that must be written to
+ obtain a complete server.</p>
+ <p>In the <c>examples/c-server</c> directory you will also find
+ source code for an Erlang client, which can be used for testing
+ the C server.</p>
+ </section>
+</chapter>
+
+