1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>Orber Stubs/Skeletons</title>
29
<date>1999-09-03</date>
34
<title>Orber Stubs and Skeletons Description</title>
35
<p>This example describes the API and behavior of Orber stubs and skeletons.
39
<title>Server Start</title>
40
<p>Orber servers can be started in several ways. The chosen start functions determines
41
how the server can be accessed and its behavior.
43
<p>Using <c>Module_Interface:oe_create()</c> or <c>oe_create_link()</c>:
45
<list type="bulleted">
46
<item>No initial data can be passed.</item>
47
<item>Cannot be used as a supervisor child start function.</item>
48
<item>Only accessible through the object reference returned by the start function.
49
The object reference is no longer valid if the server dies and is restarted.</item>
51
<p>Using <c>Module_Interface:oe_create(Env)</c> or <c>oe_create_link(Env)</c>:</p>
52
<list type="bulleted">
53
<item>Initial data can be passed using <c>Env</c>.</item>
54
<item>Cannot be used as a supervisor child start function.</item>
55
<item>Only accessible through the object reference returned by the start function.
56
The object reference is no longer valid if the server dies and is restarted.</item>
58
<p>Using <c>Module_Interface:oe_create(Env, Options)</c>:</p>
59
<list type="bulleted">
60
<item>Initial data can be passed using <c>Env</c>.</item>
61
<item>Cannot be used as a supervisor child start function.</item>
62
<item>Accessible through the object reference returned by the start function. If the option
63
<c>{regname, RegName}</c> is used the object reference stays valid even if the
64
server has been restarted.</item>
65
<item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used,
66
the result from an object invocation will be the exception 'OBJECT_NOT_EXIST'
67
only if the object has terminated with reason
68
<c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result
69
will be <c>{error, Reason}</c> or a system exception is raised.</item>
70
<item>The option <c>{pseudo, true}</c> makes it possible to start create non-server objects.
71
There are, however, some limitations, which are further described in the
72
<c>Pseudo objects</c> section.</item>
74
<p>Using <c>Module_Interface:oe_create_link(Env, Options)</c>:</p>
75
<list type="bulleted">
76
<item>Initial data can be passed using <c>Env</c>.</item>
77
<item>Can be used as a supervisor child start function if the option <c>{sup_child, true}</c> used.</item>
78
<item>Accessible through the object reference returned by the start function. If the option
79
<c>{regname, RegName}</c> is used the object reference stays valid even if the
80
server has been restarted.</item>
81
<item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used,
82
the result from an object invocation will be the exception 'OBJECT_NOT_EXIST'
83
only if the object has terminated with reason
84
<c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result
85
will be <c>{error, Reason}</c> or a system exception is raised.</item>
86
<item>For starting a server as a supervisor child you should use the options
87
<c>[{persistent, true}, {regname, {global, Name}}, {sup_child, true}]</c> and of type <em>transient</em>.
88
This configuration allows you to delegate restarts to the supervisor and still be able to
89
use the same object reference and be able to see if the server is permanently terminated.
90
Please note you must use <em>supervisor/stdlib-1.7</em> or later and that the it returns
91
<c>{ok, Pid, Object}</c> instead of just <c>Object</c>.</item>
92
<item>Using the option <c>{pseudo, true}</c> have the same effect as using
93
<c>oe_create/2</c>.</item>
96
<p>To avoid flooding Orber with old object references start erlang using the flag
97
<em>-orber objectkeys_gc_time Time</em>, which will remove all object references
98
related to servers being dead for Time seconds. To avoid extra overhead, i.e., performing
99
garbage collect if no persistent objects are started, the objectkeys_gc_time default value
100
is <em>infinity</em>. For more information, see the orber and corba documentation.</p>
103
<p>Orber still allow <c>oe_create(Env, {Type,RegName})</c> and <c>oe_create_link(Env, {Type,RegName})</c> to be used,
104
but may not in future releases.</p>
109
<title>Pseudo Objects</title>
110
<p>This section describes Orber pseudo objects.
112
<p>The Orber stub can be used to start a <c>pseudo object</c>, which will create a non-server implementation.
113
A pseudo object introduce some limitations:</p>
114
<list type="bulleted">
115
<item>The functions <c>oe_create_link/2</c> is equal to <c>oe_create/2</c>, i.e.,
116
no link can or will be created.</item>
117
<item>The <c>BIF:s self()</c> and <c>process_flag(trap_exit,true)</c> behaves incorrectly.</item>
118
<item>The <c>IC</c> option <c>{{impl, "M::I"}, "other_impl"}</c> has no effect. The call-back
119
functions must be implemented in a file called <c>M_I_impl.erl</c></item>
120
<item>The call-back functions must be implemented as if the <c>IC</c> option
121
<c>{this, "M::I"}</c> was used.</item>
122
<item>The gen_server <c>State</c> changes have no effect. The user can provide information via
123
the <c>Env</c> start parameter and the State returned from <c>init/2</c> will be the State
124
passed in following invocations.</item>
125
<item>The server reply <c>Timeout</c> has no effect.</item>
126
<item>The compile option <c>from</c> has no effect.</item>
127
<item>The option <c>{pseudo, true}</c> overrides all other start options.</item>
128
<item>Only the functions, besides own definitions, <c>init/2</c> (called via oe_create*/2) and
129
<c>terminate/2</c> (called via corba:dispose/1) must be implemented.</item>
131
<p>By adopting the rules for <c>pseudo</c> objects described above we can use <c>oe_create/2</c>
132
to create <c>server</c> or <c>pseudo</c> objects, by excluding or including the
133
option <c>{pseudo, true}</c>, without changing the call-back module.</p>
134
<p>To create a pseudo object do the following:</p>
137
Erlang (BEAM) emulator version 4.9
139
Eshell V4.9 (abort with ^G)
140
1> ic:gen(myDefinition, [{this, "MyModule::MyInterface"}]).
141
Erlang IDL compiler version 20
144
Recompile: oe_MyDefinition
145
Recompile: MyModule_MyInterface
146
Recompile: MyModule_MyInterface_impl
148
3> PseudoObj = MyModule_MyInterface:oe_create(Env, [{pseudo, true}]).
150
<p>The call-back functions must be implemented as <c>MyFunction(OE_THIS, State, Args)</c>,
151
and called by <c>MyModule_MyInterface:MyFunction(PseudoObj, Args)</c>.</p>
155
<title>Call-back Module</title>
156
<p>This section provides an example of how a call-back module may be implemented.</p>
158
<p>Arguments and Replies are determined by the IDL-code and, hence, not
159
further described here.</p>
162
%%%-----------------------------------------------------------
163
%%% File : Module_Interface_impl.erl
167
%%%-----------------------------------------------------------
169
-module('Module_Interface_impl').
171
%%--------------- INCLUDES -----------------------------------
172
-include_lib("orber/include/corba.hrl").
173
-include_lib(".. ..").
175
%%--------------- EXPORTS-------------------------------------
176
%% Arity depends on IC configuration parameters and the IDL
178
-export([own_function/X]).
181
%%--------------- gen_server specific ------------------------
182
-export([init/1, terminate/2, code_change/3, handle_info/2]).
184
%%------------------------------------------------------------
185
%% function : server specific
186
%%------------------------------------------------------------
188
%% 'trap_exit' optional (have no effect if pseudo object).
189
process_flag(trap_exit,true),
191
%%--- Possible replies ---
192
%% Reply and await next request
195
%% Reply and if no more requests within Time the special
196
%% timeout message should be handled in the
197
%% Module_Interface_impl:handle_info/2 call-back function (use the
198
%% IC option {{handle_info, "Module::Interface"}, true}).
201
%% Return ignore in order to inform the parent, especially if it is a
202
%% supervisor, that the server, as an example, did not start in
203
%% accordance with the configuration data.
205
%% If the initializing procedure fails, the reason
206
%% is supplied as StopReason.
209
terminate(Reason, State) ->
212
code_change(OldVsn, State, Extra) ->
215
%% If use IC option {{handle_info, "Module::Interface"}, true}.
216
%% (have no effect if pseudo object).
217
handle_info(Info, State) ->
218
%%--- Possible replies ---
219
%% Await the next invocation.
222
{stop, Reason, State}.
224
%%--- two-way ------------------------------------------------
225
%% If use IC option {this, "Module:Interface"}
226
%% (Required for pseudo objects)
227
own_function(This, State, .. Arguments ..) ->
228
%% IC options this and from
229
own_function(This, From, State, .. Arguments ..) ->
231
own_function(From, State, .. Arguments ..) ->
232
%% Send explicit reply to client.
233
corba:reply(From, Reply),
234
%%--- Possible replies ---
236
{noreply, State, Timeout}
239
%% If not use IC option {this, "Module:Interface"}
240
own_function(State, .. Arguments ..) ->
241
%%--- Possible replies ---
242
%% Reply and await next request
243
{reply, Reply, State}
245
%% Reply and if no more requests within Time the special
246
%% timeout message should be handled in the
247
%% Module_Interface_impl:handle_info/2 call-back function (use the
248
%% IC option {{handle_info, "Module::Interface"}, true}).
249
{reply, Reply, State, Timeout}
251
%% Stop the server and send Reply to invoking object.
252
{stop, StopReason, Reply, State}
254
%% Stop the server and send no reply to invoking object.
255
{stop, StopReason, State}
257
%% Raise exception. Any changes to the internal State is lost.
258
corba:raise(Exception).
260
%%--- one-way ------------------------------------------------
261
%% If use IC option {this, "Module:Interface"}
262
%% (Required for pseudo objects)
263
own_function(This, State, .. Arguments ..) ->
265
%% If not use IC option {this, "Module:Interface"}
266
own_function(State, .. Arguments ..) ->
267
%%--- Possible results ---
270
%% Release and if no more requests within Time the special
271
%% timeout message should be handled in the
272
%% Module_Interface_impl:handle_info/2 call-back function (use the
273
%% IC option {{handle_info, "Module::Interface"}, true}).
274
{noreply, State, Timeout}
276
%% Stop the server with StopReason.
277
{stop, StopReason, State}
279
%%--------------- END OF MODULE ------------------------------
added
removed
lib/orber/doc/src/ch_stubs.xml
