From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/orber/doc/src/ch_stubs.xml | 283 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 lib/orber/doc/src/ch_stubs.xml (limited to 'lib/orber/doc/src/ch_stubs.xml') 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 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Orber Stubs/Skeletons + + + 1999-09-03 + A + ch_stubs.xml +
+ +
+ Orber Stubs and Skeletons Description +

This example describes the API and behavior of Orber stubs and skeletons. +

+ +
+ Server Start +

Orber servers can be started in several ways. The chosen start functions determines + how the server can be accessed and its behavior. +

+

Using Module_Interface:oe_create() or oe_create_link(): +

+ + No initial data can be passed. + Cannot be used as a supervisor child start function. + 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. + +

Using Module_Interface:oe_create(Env) or oe_create_link(Env):

+ + Initial data can be passed using Env. + Cannot be used as a supervisor child start function. + 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. + +

Using Module_Interface:oe_create(Env, Options):

+ + Initial data can be passed using Env. + Cannot be used as a supervisor child start function. + Accessible through the object reference returned by the start function. If the option + {regname, RegName} is used the object reference stays valid even if the + server has been restarted. + If the options {persistent, true} and {regname, {global, Name}} is used, + the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' + only if the object has terminated with reason + normal or shutdown. If the object is in the process of restarting, the result + will be {error, Reason} or a system exception is raised. + The option {pseudo, true} makes it possible to start create non-server objects. + There are, however, some limitations, which are further described in the + Pseudo objects section. + +

Using Module_Interface:oe_create_link(Env, Options):

+ + Initial data can be passed using Env. + Can be used as a supervisor child start function if the option {sup_child, true} used. + Accessible through the object reference returned by the start function. If the option + {regname, RegName} is used the object reference stays valid even if the + server has been restarted. + If the options {persistent, true} and {regname, {global, Name}} is used, + the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' + only if the object has terminated with reason + normal or shutdown. If the object is in the process of restarting, the result + will be {error, Reason} or a system exception is raised. + For starting a server as a supervisor child you should use the options + [{persistent, true}, {regname, {global, Name}}, {sup_child, true}] and of type transient. + 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 supervisor/stdlib-1.7 or later and that the it returns + {ok, Pid, Object} instead of just Object. + Using the option {pseudo, true} have the same effect as using + oe_create/2. + + +

To avoid flooding Orber with old object references start erlang using the flag + -orber objectkeys_gc_time Time, 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 infinity. For more information, see the orber and corba documentation.

+ + +

Orber still allow oe_create(Env, {Type,RegName}) and oe_create_link(Env, {Type,RegName}) to be used, + but may not in future releases.

+ +
+ +
+ Pseudo Objects +

This section describes Orber pseudo objects. +

+

The Orber stub can be used to start a pseudo object, which will create a non-server implementation. + A pseudo object introduce some limitations:

+ + The functions oe_create_link/2 is equal to oe_create/2, i.e., + no link can or will be created. + The BIF:s self() and process_flag(trap_exit,true) behaves incorrectly. + The IC option {{impl, "M::I"}, "other_impl"} has no effect. The call-back + functions must be implemented in a file called M_I_impl.erl + The call-back functions must be implemented as if the IC option + {this, "M::I"} was used. + The gen_server State changes have no effect. The user can provide information via + the Env start parameter and the State returned from init/2 will be the State + passed in following invocations. + The server reply Timeout has no effect. + The compile option from has no effect. + The option {pseudo, true} overrides all other start options. + Only the functions, besides own definitions, init/2 (called via oe_create*/2) and + terminate/2 (called via corba:dispose/1) must be implemented. + +

By adopting the rules for pseudo objects described above we can use oe_create/2 + to create server or pseudo objects, by excluding or including the + option {pseudo, true}, without changing the call-back module.

+

To create a pseudo object do the following:

+ +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}]). + +

The call-back functions must be implemented as MyFunction(OE_THIS, State, Args), + and called by MyModule_MyInterface:MyFunction(PseudoObj, Args).

+
+ +
+ Call-back Module +

This section provides an example of how a call-back module may be implemented.

+ +

Arguments and Replies are determined by the IDL-code and, hence, not + further described here.

+ + +%%%----------------------------------------------------------- +%%% 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 ------------------------------ + +
+
+ + -- cgit v1.2.3