aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ch_erl_genserv.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_erl_genserv.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_erl_genserv.xml')
-rw-r--r--lib/ic/doc/src/ch_erl_genserv.xml205
1 files changed, 205 insertions, 0 deletions
diff --git a/lib/ic/doc/src/ch_erl_genserv.xml b/lib/ic/doc/src/ch_erl_genserv.xml
new file mode 100644
index 0000000000..972eff7c17
--- /dev/null
+++ b/lib/ic/doc/src/ch_erl_genserv.xml
@@ -0,0 +1,205 @@
+<?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>Using the Erlang Generic Server Back-end</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date>98-08-06</date>
+ <rev>B</rev>
+ <file>ch_erl_genserver.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+ <p>The mapping of OMG IDL to the Erlang programming language when Erlang
+ generic server is the back-end of choice is similar to the one used in
+ the chapter 'OMG IDL Mapping'.
+ The only difference is in the generated code, a client stub and
+ server skeleton to an Erlang <c>gen_server</c>. Orber's User's Guide
+ contain a more detailed description of IDL to Erlang mapping.</p>
+ </section>
+
+ <section>
+ <title>Compiling the Code</title>
+ <p>The <c>ic:gen/2</c> function can be called from the command
+ line as follows:</p>
+ <p></p>
+ <code type="none">
+shell> erlc "+{be, erl_genserv}" MyFile.idl
+ </code>
+ </section>
+
+ <section>
+ <title>Writing the Implementation File</title>
+ <p>For each IDL interface <c><![CDATA[<interface name>]]></c> defined in the IDL file :</p>
+ <list type="bulleted">
+ <item>Create the corresponding Erlang file that will hold the
+ Erlang implementation of the IDL definitions. </item>
+ <item>Call the implementation file after the scope of the IDL interface,
+ followed by the suffix <c>_impl</c>.</item>
+ <item>Export the implementation functions.</item>
+ </list>
+ <p>For each function defined in the IDL interface :</p>
+ <list type="bulleted">
+ <item>Implement an Erlang function that uses as arguments in the same
+ order, as the input arguments described in the IDL file, and returns
+ the value described in the interface.</item>
+ <item>When using the function, follow the mapping described in chapter 2.</item>
+ </list>
+ </section>
+
+ <section>
+ <title>An Example</title>
+ <p>In this example, a file <c>random.idl</c> generates code for the Erlang
+ gen_server back-end:</p>
+ <code type="none">
+// Filename random.idl
+module rmod {
+
+ interface random {
+ // Generate a new random number
+ double produce();
+ // Initialize random generator
+ oneway void init(in long seed1, in long seed2, in long seed3);
+
+ };
+};
+ </code>
+ <p>When the file "random.idl" is compiled (e.g., <c>shell> erlc "+{be, erl_genserv}" random.idl</c>)
+ five files are produced; two for the top scope, two for the interface scope,
+ and one for the module scope. The header files for top scope and interface
+ are empty and not shown here. In this case, the stub/skeleton file
+ <c>rmod_random.erl</c> is the most important. This module exports two kinds of
+ operations:</p>
+ <list type="bulleted">
+ <item><em>Administrative</em> - used when, for example, creating and
+ terminating the server.</item>
+ <item><em>IDL dependent</em> - operations defined in the IDL
+ specification. In this case, <c>produce</c> and <c>init</c>.</item>
+ </list>
+
+ <section>
+ <title>Administrative Operations</title>
+ <p>To create a new server instance, one of the following functions should
+ be used:</p>
+ <list type="bulleted">
+ <item><em>oe_create/0/1/2</em> - create a new instance of the object.
+ Accepts <c>Env</c> and <c>RegName</c>, in that order, as parameters.
+ The former is passed uninterpreted to the initialization operation
+ of the call-back module, while the latter must be as the
+ <c>gen_server</c> parameter <c>ServerName</c>. If <c>Env</c> is
+ left out, an empty list will be passed.</item>
+ <item><em>oe_create_link/0/1/2</em> - similar to <c>oe_create/0/1/2</c>,
+ but create a linked server.</item>
+ <item><em>typeID/0</em> - returns the scooped id compliant with the
+ OMG standard. In this case the string
+ <c>"IDL:rmod/random:1.0"</c>.</item>
+ <item><em>stop/1</em> - asynchronously terminate the server. The required
+ argument is the return value from any of the start functions.</item>
+ </list>
+ </section>
+
+ <section>
+ <title>IDL Dependent Operations</title>
+ <p>Operations can either be synchronous or asynchronous
+ (i.e., <c>oneway</c>). These are, respectively, mapped to
+ <c>gen_server:call/2/3</c> and <c>gen_server:cast/2</c>.
+ Consult the <c>gen_server</c> documentation for valid return values.</p>
+ <p>The IDL dependent operations in this example are listed below.
+ The first argument must be the whatever the create operation returned.</p>
+ <list type="bulleted">
+ <item><em>init(ServerReference, Seed1, Seed2, Seed3)</em> - initialize
+ the random number generator.</item>
+ <item><em>produce(ServerReference)</em> - generate a new random number.</item>
+ </list>
+ </section>
+ <p>If the compile option <c>timeout</c> is used a timeout must be added
+ (e.g., <c>produce(ServerReference, 5000)</c>). For more information, see
+ the <c>gen_server</c> documentation.</p>
+
+ <section>
+ <title>Implementation Module</title>
+ <p>The implementation module shall, unless the compile option
+ <c>impl</c> is used, be named <c>rmod_random_impl.erl</c>.
+ and could look like this:</p>
+ <code type="none">
+-module('rmod_random_impl').
+%% Mandatory gen_server operations
+-export([init/1, terminate/2, code_change/3]).
+%% Add if 'handle_info' compile option used
+-export([handle_info/2]).
+%% API defined in IDL specification
+-export([produce/1,init/4]).
+
+%% Mandatory operations
+init(Env) ->
+ {ok, []}.
+
+terminate(From, Reason) ->
+ ok.
+
+code_change(OldVsn, State, Extra) ->
+ {ok, State}.
+
+%% Optional
+handle_info(Info, State) ->
+ {noreply, NewState}.
+
+%% IDL specification
+produce(State) ->
+ case catch random:uniform() of
+\\011{'EXIT',_} ->
+\\011 {stop, normal, "random:uniform/0 - EXIT", State};
+\\011RUnif ->
+ {reply, RUnif, State}
+ end.
+
+
+init(State, S1, S2, S3) ->
+ case catch random:seed(S1, S2, S3) of
+\\011{'EXIT',_} ->
+\\011 {stop, normal, State};
+\\011_ ->
+ {noreply, State}
+ end.
+ </code>
+ <p>Compile the code and run the example:</p>
+ <code type="none"><![CDATA[
+1> make:all().
+Recompile: rmod_random
+Recompile: oe_random
+Recompile: rmod_random_impl
+up_to_date
+2> {ok,R} = rmod_random:oe_create().
+{ok,<0.30.0>}
+3> rmod_random:init(R, 1, 2, 3).
+ok
+4> rmod_random:produce(R).
+1.97963e-4
+5>
+ ]]></code>
+ </section>
+ </section>
+</chapter>
+
+