diff options
Diffstat (limited to 'lib/ic/doc/src/ch_erl_genserv.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_erl_genserv.xml | 206 |
1 files changed, 0 insertions, 206 deletions
diff --git a/lib/ic/doc/src/ch_erl_genserv.xml b/lib/ic/doc/src/ch_erl_genserv.xml deleted file mode 100644 index aa162b3652..0000000000 --- a/lib/ic/doc/src/ch_erl_genserv.xml +++ /dev/null @@ -1,206 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</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>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 - {'EXIT',_} -> - {stop, normal, "random:uniform/0 - EXIT", State}; - RUnif -> - {reply, RUnif, State} - end. - - -init(State, S1, S2, S3) -> - case catch random:seed(S1, S2, S3) of - {'EXIT',_} -> - {stop, normal, State}; - _ -> - {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> - - |