diff options
Diffstat (limited to 'lib/orber/doc/src/ch_stubs.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_stubs.xml | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/lib/orber/doc/src/ch_stubs.xml b/lib/orber/doc/src/ch_stubs.xml new file mode 100644 index 0000000000..785805a4d6 --- /dev/null +++ b/lib/orber/doc/src/ch_stubs.xml @@ -0,0 +1,283 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</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>Orber Stubs/Skeletons</title> + <prepared></prepared> + <docno></docno> + <date>1999-09-03</date> + <rev>A</rev> + <file>ch_stubs.xml</file> + </header> + + <section> + <title>Orber Stubs and Skeletons Description</title> + <p>This example describes the API and behavior of Orber stubs and skeletons. + </p> + + <section> + <title>Server Start</title> + <p>Orber servers can be started in several ways. The chosen start functions determines + how the server can be accessed and its behavior. + </p> + <p>Using <c>Module_Interface:oe_create()</c> or <c>oe_create_link()</c>: + </p> + <list type="bulleted"> + <item>No initial data can be passed.</item> + <item>Cannot be used as a supervisor child start function.</item> + <item>Only accessible through the object reference returned by the start function. + The object reference is no longer valid if the server dies and is restarted.</item> + </list> + <p>Using <c>Module_Interface:oe_create(Env)</c> or <c>oe_create_link(Env)</c>:</p> + <list type="bulleted"> + <item>Initial data can be passed using <c>Env</c>.</item> + <item>Cannot be used as a supervisor child start function.</item> + <item>Only accessible through the object reference returned by the start function. + The object reference is no longer valid if the server dies and is restarted.</item> + </list> + <p>Using <c>Module_Interface:oe_create(Env, Options)</c>:</p> + <list type="bulleted"> + <item>Initial data can be passed using <c>Env</c>.</item> + <item>Cannot be used as a supervisor child start function.</item> + <item>Accessible through the object reference returned by the start function. If the option + <c>{regname, RegName}</c> is used the object reference stays valid even if the + server has been restarted.</item> + <item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used, + the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' + only if the object has terminated with reason + <c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result + will be <c>{error, Reason}</c> or a system exception is raised.</item> + <item>The option <c>{pseudo, true}</c> makes it possible to start create non-server objects. + There are, however, some limitations, which are further described in the + <c>Pseudo objects</c> section.</item> + </list> + <p>Using <c>Module_Interface:oe_create_link(Env, Options)</c>:</p> + <list type="bulleted"> + <item>Initial data can be passed using <c>Env</c>.</item> + <item>Can be used as a supervisor child start function if the option <c>{sup_child, true}</c> used.</item> + <item>Accessible through the object reference returned by the start function. If the option + <c>{regname, RegName}</c> is used the object reference stays valid even if the + server has been restarted.</item> + <item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used, + the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' + only if the object has terminated with reason + <c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result + will be <c>{error, Reason}</c> or a system exception is raised.</item> + <item>For starting a server as a supervisor child you should use the options + <c>[{persistent, true}, {regname, {global, Name}}, {sup_child, true}]</c> and of type <em>transient</em>. + This configuration allows you to delegate restarts to the supervisor and still be able to + use the same object reference and be able to see if the server is permanently terminated. + Please note you must use <em>supervisor/stdlib-1.7</em> or later and that the it returns + <c>{ok, Pid, Object}</c> instead of just <c>Object</c>.</item> + <item>Using the option <c>{pseudo, true}</c> have the same effect as using + <c>oe_create/2</c>.</item> + </list> + <warning> + <p>To avoid flooding Orber with old object references start erlang using the flag + <em>-orber objectkeys_gc_time Time</em>, which will remove all object references + related to servers being dead for Time seconds. To avoid extra overhead, i.e., performing + garbage collect if no persistent objects are started, the objectkeys_gc_time default value + is <em>infinity</em>. For more information, see the orber and corba documentation.</p> + </warning> + <warning> + <p>Orber still allow <c>oe_create(Env, {Type,RegName})</c> and <c>oe_create_link(Env, {Type,RegName})</c> to be used, + but may not in future releases.</p> + </warning> + </section> + + <section> + <title>Pseudo Objects</title> + <p>This section describes Orber pseudo objects. + </p> + <p>The Orber stub can be used to start a <c>pseudo object</c>, which will create a non-server implementation. + A pseudo object introduce some limitations:</p> + <list type="bulleted"> + <item>The functions <c>oe_create_link/2</c> is equal to <c>oe_create/2</c>, i.e., + no link can or will be created.</item> + <item>The <c>BIF:s self()</c> and <c>process_flag(trap_exit,true)</c> behaves incorrectly.</item> + <item>The <c>IC</c> option <c>{{impl, "M::I"}, "other_impl"}</c> has no effect. The call-back + functions must be implemented in a file called <c>M_I_impl.erl</c></item> + <item>The call-back functions must be implemented as if the <c>IC</c> option + <c>{this, "M::I"}</c> was used.</item> + <item>The gen_server <c>State</c> changes have no effect. The user can provide information via + the <c>Env</c> start parameter and the State returned from <c>init/2</c> will be the State + passed in following invocations.</item> + <item>The server reply <c>Timeout</c> has no effect.</item> + <item>The compile option <c>from</c> has no effect.</item> + <item>The option <c>{pseudo, true}</c> overrides all other start options.</item> + <item>Only the functions, besides own definitions, <c>init/2</c> (called via oe_create*/2) and + <c>terminate/2</c> (called via corba:dispose/1) must be implemented.</item> + </list> + <p>By adopting the rules for <c>pseudo</c> objects described above we can use <c>oe_create/2</c> + to create <c>server</c> or <c>pseudo</c> objects, by excluding or including the + option <c>{pseudo, true}</c>, without changing the call-back module.</p> + <p>To create a pseudo object do the following:</p> + <code type="none"> +fingolfin 127> erl +Erlang (BEAM) emulator version 4.9 + +Eshell V4.9 (abort with ^G) +1> ic:gen(myDefinition, [{this, "MyModule::MyInterface"}]). +Erlang IDL compiler version 20 +ok +2> make:all(). +Recompile: oe_MyDefinition +Recompile: MyModule_MyInterface +Recompile: MyModule_MyInterface_impl +up_to_date +3> PseudoObj = MyModule_MyInterface:oe_create(Env, [{pseudo, true}]). + </code> + <p>The call-back functions must be implemented as <c>MyFunction(OE_THIS, State, Args)</c>, + and called by <c>MyModule_MyInterface:MyFunction(PseudoObj, Args)</c>.</p> + </section> + + <section> + <title>Call-back Module</title> + <p>This section provides an example of how a call-back module may be implemented.</p> + <note> + <p>Arguments and Replies are determined by the IDL-code and, hence, not + further described here.</p> + </note> + <code type="none"> +%%%----------------------------------------------------------- +%%% File : Module_Interface_impl.erl +%%% Author : +%%% Purpose : +%%% Created : +%%%----------------------------------------------------------- + +-module('Module_Interface_impl'). + +%%--------------- INCLUDES ----------------------------------- +-include_lib("orber/include/corba.hrl"). +-include_lib(".. .."). + +%%--------------- EXPORTS------------------------------------- +%% Arity depends on IC configuration parameters and the IDL +%% specification. +-export([own_function/X]). + + +%%--------------- gen_server specific ------------------------ +-export([init/1, terminate/2, code_change/3, handle_info/2]). + +%%------------------------------------------------------------ +%% function : server specific +%%------------------------------------------------------------ +init(InitialData) -> + %% 'trap_exit' optional (have no effect if pseudo object). + process_flag(trap_exit,true), + + %%--- Possible replies --- + %% Reply and await next request + {ok, State}. + + %% Reply and if no more requests within Time the special + %% timeout message should be handled in the + %% Module_Interface_impl:handle_info/2 call-back function (use the + %% IC option {{handle_info, "Module::Interface"}, true}). + {ok, State, Timeout} + + %% Return ignore in order to inform the parent, especially if it is a + %% supervisor, that the server, as an example, did not start in + %% accordance with the configuration data. + ignore + %% If the initializing procedure fails, the reason + %% is supplied as StopReason. + {stop, StopReason} + +terminate(Reason, State) -> + ok. + +code_change(OldVsn, State, Extra) -> + {ok, NewState}. + +%% If use IC option {{handle_info, "Module::Interface"}, true}. +%% (have no effect if pseudo object). +handle_info(Info, State) -> + %%--- Possible replies --- + %% Await the next invocation. + {noreply, State}. + %% Stop with Reason. + {stop, Reason, State}. + +%%--- two-way ------------------------------------------------ +%% If use IC option {this, "Module:Interface"} +%% (Required for pseudo objects) +own_function(This, State, .. Arguments ..) -> +%% IC options this and from +own_function(This, From, State, .. Arguments ..) -> +%% IC option from +own_function(From, State, .. Arguments ..) -> + %% Send explicit reply to client. + corba:reply(From, Reply), + %%--- Possible replies --- + {noreply, State} + {noreply, State, Timeout} + + +%% If not use IC option {this, "Module:Interface"} +own_function(State, .. Arguments ..) -> + %%--- Possible replies --- + %% Reply and await next request + {reply, Reply, State} + + %% Reply and if no more requests within Time the special + %% timeout message should be handled in the + %% Module_Interface_impl:handle_info/2 call-back function (use the + %% IC option {{handle_info, "Module::Interface"}, true}). + {reply, Reply, State, Timeout} + + %% Stop the server and send Reply to invoking object. + {stop, StopReason, Reply, State} + + %% Stop the server and send no reply to invoking object. + {stop, StopReason, State} + + %% Raise exception. Any changes to the internal State is lost. + corba:raise(Exception). + +%%--- one-way ------------------------------------------------ +%% If use IC option {this, "Module:Interface"} +%% (Required for pseudo objects) +own_function(This, State, .. Arguments ..) -> + +%% If not use IC option {this, "Module:Interface"} +own_function(State, .. Arguments ..) -> + %%--- Possible results --- + {noreply, State} + + %% Release and if no more requests within Time the special + %% timeout message should be handled in the + %% Module_Interface_impl:handle_info/2 call-back function (use the + %% IC option {{handle_info, "Module::Interface"}, true}). + {noreply, State, Timeout} + + %% Stop the server with StopReason. + {stop, StopReason, State} + +%%--------------- END OF MODULE ------------------------------ + </code> + </section> + </section> +</chapter> + |