diff options
Diffstat (limited to 'lib/orber/doc/src/ch_stubs.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_stubs.xml | 284 |
1 files changed, 0 insertions, 284 deletions
diff --git a/lib/orber/doc/src/ch_stubs.xml b/lib/orber/doc/src/ch_stubs.xml deleted file mode 100644 index 9290c127f9..0000000000 --- a/lib/orber/doc/src/ch_stubs.xml +++ /dev/null @@ -1,284 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1999</year><year>2017</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>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="erl"> -%%%----------------------------------------------------------- -%%% 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> - |