Module_Interface(3)

📦
version 5.2.2 · 2 versions
, in fedora 43, fedora 44

🦋 Module_Interface(3) — Erlang Module Definition 🦋

okay bestie, buckle up — this is the Erlang manual page for Module_Interface and it's a whole journey. grab a boba, we're going in 💖

✨ NAME ✨

Module_Interface — the Orber generated stubs/skeletons. that's it, that's the name, she's simple and she knows it 🎀

🌸 DESCRIPTION 🌸

This module contains the stub/skeleton functions generated by IC. no cap, IC just hands you these and you go off 💅

Starting a Orber server can be done in three ways:

  • Normal — when the server dies, Orber forgets all knowledge of the server. like, who? never met her 💀
  • Supervisor child — add the configuration parameter {sup_child, true} and the oe_create_link/2 function returns {ok, Pid, ObjRef}, which can be handled by the application supervisor/stdlib-1.7 or later. she's got a babysitter now 🍼
  • Persistent object reference — add the configuration parameters {persistent, true} and {regname, {global, term()}} and Orber will remember the object reference until the server terminates with reason normal or shutdown. Hence, if the server is started as a transient supervisor child we do not receive a 'OBJECT_NOT_EXIST' exception when it has crashed and is being restarted. she has main character memory ✨

The Orber stub can be used to start a pseudo object, which will create a non-server implementation. A pseudo object introduces some limitations, and bestie, there are a lot of them:

  • 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 IC option from has no effect.
  • The call-back functions must be implemented as if the IC option {this, "M::I"} was used.
  • 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 state is giving "frozen in time" 🧊
  • If a call-back function replies with the Timeout parameter set it have no effect.
  • Operations defined as oneway are blocking until the operation replies. (yes, that's as cursed as it sounds 💀)
  • The option {pseudo, true} overrides all other start options. she's the final boss 👑
  • 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. slay, one codebase, two vibes 🦋

If you start a object without {regname, RegName} it can only be accessed through the returned object key. Started with a {regname, RegName} the name is registered locally or globally.

⚠️ Warning ⚠️

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.

like, fr fr, clean up your old refs or Orber will just be hoarding them forever 🙈

📦 EXPORTS 📦

💫 Module_Interface:typeID() -> TypeId

Types:

TypeId = string(), e.g., "IDL:Module/Interface:1.0"

Returns the Type ID related to this stub/skeleton. that's her government name 💅

💫 Module_Interface:oe_create() -> ObjRef

Types:

ObjRef = #object reference

Start a Orber server. 🚀

Types:

ObjRef = #object reference

Start a linked Orber server. 🔗

💫 Module_Interface:oe_create(Env) -> ObjRef

Types:

Env = term()
ObjRef = #object reference

Start a Orber server passing Env to init/1. ✨

Types:

Env = term()
ObjRef = #object reference

Start a linked Orber server passing Env to init/1. 🔗✨

💫 Module_Interface:oe_create(Env, Options) -> ObjRef

Types:

Env = term()
ObjRef = #object reference
Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]
Bool = true | false
RegName = {global, term()} | {local, atom()}
CreateOpts = {debug, [Dbg]} | {timeout, Time}
Dbg = trace | log | statistics | {log_to_file, FileName}

Start a Orber server passing Env to init/1. 🌈

If the option {pseudo, true} is used, all other options are overridden. As default, this option is set to false.

This function cannot be used for starting a server as supervisor child. If started as persistent, the options [{persistent, true}, {regname, {global, term()}}] must be used and Orber will only forget the object reference if it terminates with reason normal or shutdown.

The option {local_typecheck, boolean()}, which overrides the Local Typechecking environment flag, turns on or off typechecking. If activated, parameters, replies and raised exceptions will be checked to ensure that the data is correct, when invoking operations on CORBA Objects within the same Orber domain. Due to the extra overhead, this option MAY ONLY be used during testing and development. 🧪 like, do NOT ship this, bestie, I'm begging 🙏

{survive_exit, boolean()} overrides the EXIT Tolerance environment flag. If activated, the server will not terminate, even though the call-back module returns EXIT. she simply refuses to go 💅

Time specifies how long time, in milliseconds, the server is allowed to spend initializing. For more information about the Dbg options, see the sys module.

Types:

Env = term()
Return = ObjRef | {ok, Pid, ObjRef}
ObjRef = #object reference
Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]
Bool = true | false
RegName = {global, term()} | {local, atom()}
CreateOpts = {debug, [Dbg]} | {timeout, Time}
Dbg = trace | log | statistics | {log_to_file, FileName}

Start a linked Orber server passing Env to init/1. 🔗

If the option {pseudo, true} is used, all other options are overridden and no link will be created. As default, this option is set to false.

This function can be used for starting a server as persistent or supervisor child. At the moment [{persistent, true}, {regname, {global, term()}}] must be used to start a server as persistent, i.e., if a server died and is in the process of being restarted a call to the server will not raise 'OBJECT_NOT_EXIST' exception. Orber will only forget the object reference if it terminates with reason normal or shutdown, hence, the server must be started as transient (for more information see the supervisor documentation).

The options {local_typecheck, boolean()} and {survive_exit, boolean()} behaves in the same way as for oe_create/2.

Time specifies how long time, in milliseconds, the server is allowed to spend initializing. For more information about the Dbg options, see the sys module.

💫 Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply 💫 Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply

Types:

ObjRef = #object reference
Options = [Option] | Timeout
Option = {timeout, Timeout} | {context, [Context]}
Timeout = infinity | integer(milliseconds)
Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
CtxId = ?ORBER_GENERIC_CTX_ID
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
Interface = string()
Options = [{Key, Value}]
Key = ssl_client_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout
Value = allowed value associated with the given key
ArgX = specified in the IDL-code.
Reply = specified in the IDL-code.

The default value for the Timeout option is infinity. IPv4 or IPv6 addresses are accepted as local Interface. 🌐

The configuration context is used to override the global SSL client side configuration. 🔐

To gain access to #'IOP_ServiceContext'{} record and the ?ORBER_GENERIC_CTX_ID macro, you must add -include_lib("orber/include/corba.hrl"). to your module. don't forget her, she's essential 🫶

🎀 CALLBACK FUNCTIONS 🎀

The following functions should be exported from a CORBA callback module. Note, a complete template of the call-back module can be generated automatically by compiling the IDL-file with the IC option {be,erl_template}. One should also add the same compile options, for example this or from, used when generating the stub/skeleton modules. 💖

⏳ okay bestie that's part 1 — the callback functions themselves are rolling up in part 2, don't go anywhere 🌸

okay bestie, now that we know what the callbacks are, here's the whole roster — every single one, what it takes, what it hands back, no skips 💅

🌱 Module_Interface_impl:init(Env) -> CallReply

Types:

  • Env = term()
  • CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}
  • State = term()
  • Timeout = int() >= 0 | infinity
  • StopReason = term()

Every time a new server gets started, init/1 is the very first function called in the call-back module you specified. it's giving first-day-of-school energy, it goes first, no debate ✨

🥀 Module_Interface_impl:terminate(Reason, State) -> ok

Types:

  • Reason = term()
  • State = term()

This call-back function gets called whenever the server is about to terminate. so like… the goodbye scene 😭

🔄 Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply

Types:

  • OldVsn = undefined | term()
  • State = term()
  • Extra = term()
  • CallReply = {ok, NewState}
  • NewState = term()

Update the internal State. glow-up arc, literally 🦋

📬 Module_Interface_impl:handle_info(Info, State) -> CallReply

Types:

  • Info = term()
  • State = term()
  • CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
  • Timeout = int() >= 0 | infinity
  • StopReason = normal | shutdown | term()

If the configuration parameter {{handle_info, "Module::Interface"}, true} is passed to IC and process_flag(trap_exit,true) is set in the init() call-back, this function must be exported. no ifs, no buts, bestie 👑

Note: To be able to handle the Timeout option in CallReply in the call-back module, the configuration parameter {{handle_info, "Module::Interface"}, true} must be passed to IC. like, mandatory mandatory 🙈

🎀 two-way own_functions — the ones that answer back

Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply
Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply
Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply
Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply

Types:

  • This = the servers #object reference
  • State = term()
  • ArgX = specified in the IDL-code.
  • CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)
  • ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}
  • Reply = specified in the IDL-code.
  • Timeout = int() >= 0 | infinity
  • StopReason = normal | shutdown | term()

All two-way functions must return one of the listed replies, or raise any of the exceptions listed in the IDL code (i.e. raises(...)). And if the IC compile options this and/or from are used, then your implementation has to accept the This and/or From parameters. no dodging them, they're coming whether you like it or not 💀

🍓 one-way own_functions — the ones that just yeet and go

Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply
Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply

Types:

  • This = the servers #object reference
  • State = term()
  • CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
  • ArgX = specified in the IDL-code.
  • Reply = specified in the IDL-code.
  • Timeout = int() >= 0 | infinity
  • StopReason = normal | shutdown | term()

All one-way functions must return one of the listed replies. And if the IC compile option this is used, your implementation must accept the This parameter. same deal, different vibe 🌈

and that's the whole page, bestie — you ate it 🫶 this iconic little manual comes from Ericsson AB, and it's the orber 5.2.2 version of Module_Interface(3). go forth and write ur callbacks, you're literally the main character 👑💖

📦 where this page comes from