The R13B03 release.OTP_R13B03

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>
+
+