diff options
Diffstat (limited to 'lib/ic/doc/src/ch_erl_genserv.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_erl_genserv.xml | 205 |
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> + + |