pub struct Orb { /* private fields */ }Expand description
An ORB: the client side, and the server side once the RootPOA is used.
Network I/O runs on a tokio runtime owned by the ORB, or on one the
application shares with it (with_runtime); the
methods here and on ObjectRef block the calling thread. They must
not be called from inside a tokio runtime, the threads of
spawn_blocking included (they fail with BAD_INV_ORDER): async code
uses ObjectRef::request_async and run_async
instead. Servants run on a pool of upcall threads owned by the ORB.
Orb is a cheap handle: clones share the same ORB, which shuts down
when the last clone and the last ObjectRef are gone. Servants that
hold the ORB keep it alive until shutdown or
destroy drops them.
Implementations§
Source§impl Orb
impl Orb
Sourcepub fn init(args: &mut Vec<String>) -> Result<Orb, SystemException>
pub fn init(args: &mut Vec<String>) -> Result<Orb, SystemException>
Initialises an ORB from command line arguments, removing the ORB
options (see OrbOptions::parse_args).
Sourcepub fn with_options(options: OrbOptions) -> Result<Orb, SystemException>
pub fn with_options(options: OrbOptions) -> Result<Orb, SystemException>
Initialises an ORB with options. Fails with the exception of an
OrbInitializer that failed.
Sourcepub fn with_runtime(options: OrbOptions, handle: Handle) -> Orb
pub fn with_runtime(options: OrbOptions, handle: Handle) -> Orb
Initialises an ORB with options whose network I/O runs on the
application’s runtime handle instead of a runtime of its own
(OrbOptions::io_threads is not used). The runtime must have I/O
and time enabled. A current_thread runtime does I/O only while a
thread runs its block_on, so blocking calls (from servants, say)
wait until one does; a multi-thread runtime has no such limit.
Shutting the ORB down needs the runtime to run. On a
current_thread runtime, a blocking shutdown(true)
or destroy outside its block_on waits for it, and
inside it blocks the runtime: shut down from inside instead, with
shutdown(false) and run_async, and destroy
after that.
Destroy the ORB before the runtime shuts down. Destroying it closes
its connections and stops its listening tasks; the runtime keeps no
task of the ORB. Once the runtime is gone, calls fail with
COMM_FAILURE or TRANSIENT.
When an OrbInitializer fails, the
ORB is returned shut down (calls fail with BAD_INV_ORDER); use
try_with_runtime to get the exception.
Sourcepub fn try_with_runtime(
options: OrbOptions,
handle: Handle,
) -> Result<Orb, SystemException>
pub fn try_with_runtime( options: OrbOptions, handle: Handle, ) -> Result<Orb, SystemException>
with_runtime, failing with the exception of
an OrbInitializer that failed.
Sourcepub fn pi_current(&self) -> PiCurrent
pub fn pi_current(&self) -> PiCurrent
resolve_initial_references("PICurrent"): the slots of the
Portable Interceptors for the calling thread.
Sourcepub fn codec_factory(&self) -> CodecFactory
pub fn codec_factory(&self) -> CodecFactory
resolve_initial_references("CodecFactory").
Sourcepub fn runtime_handle(&self) -> &Handle
pub fn runtime_handle(&self) -> &Handle
The handle of the runtime the ORB’s network I/O runs on: its own,
or the one given to with_runtime.
Sourcepub fn options(&self) -> &OrbOptions
pub fn options(&self) -> &OrbOptions
The options the ORB was created with.
Sourcepub fn set_call_timeout(&self, timeout: Option<Duration>)
pub fn set_call_timeout(&self, timeout: Option<Duration>)
Sets how long calls through this ORB may take (None: no limit),
like omniORB’s setClientCallTimeout(millisecs). The time covers
connecting (unless a connect timeout
is set), following forwards and waiting for the reply. When it
expires the call raises TIMEOUT: completed maybe once the request
was sent, and then a CancelRequest goes to the server; completed
no before.
A timeout of the calling thread
(set_thread_call_timeout)
overrides it, one of the object reference
(ObjectRef::set_call_timeout) overrides both, and one given for
the request (Request::timeout) all of
them.
Sourcepub fn call_timeout(&self) -> Option<Duration>
pub fn call_timeout(&self) -> Option<Duration>
The timeout set_call_timeout set, or
OrbOptions::request_timeout.
Sourcepub fn set_connect_timeout(&self, timeout: Option<Duration>)
pub fn set_connect_timeout(&self, timeout: Option<Duration>)
Sets how long to wait for a new TCP connection, like omniORB’s
setClientConnectTimeout: while connecting it replaces the call
timeout. None connects until the call timeout expires, or as long
as the operating system waits. Expiry raises TIMEOUT, completed
no.
Sourcepub fn connect_timeout(&self) -> Option<Duration>
pub fn connect_timeout(&self) -> Option<Duration>
The timeout set_connect_timeout set,
or OrbOptions::connect_timeout.
Sourcepub fn string_to_object(
&self,
s: &str,
) -> Result<Option<ObjectRef>, SystemException>
pub fn string_to_object( &self, s: &str, ) -> Result<Option<ObjectRef>, SystemException>
Turns a stringified IOR, a corbaloc: or a corbaname: URL into a
reference. Returns None for a nil IOR, or a name bound to nil.
corbaloc:rir: goes through
resolve_initial_references.
corbaname: resolves the name after # in the naming context the
rest of the URL denotes (with no name, the context itself is
returned). The name must be a valid stringified name
(BAD_PARAM, minor BAD_SCHEME_SPECIFIC_PART); a name the naming
service cannot resolve raises BAD_PARAM with minor
STRING_TO_OBJECT_OTHER, and system exceptions from the naming
service are passed on.
Sourcepub fn object_to_string(
&self,
obj: Option<&ObjectRef>,
) -> Result<String, SystemException>
pub fn object_to_string( &self, obj: Option<&ObjectRef>, ) -> Result<String, SystemException>
Writes a reference as a stringified IOR; None gives the nil IOR.
Sourcepub fn resolve_initial_references(
&self,
name: &str,
) -> Result<ObjectRef, ResolveError>
pub fn resolve_initial_references( &self, name: &str, ) -> Result<ObjectRef, ResolveError>
Looks up an initial reference: first among those
registered, then in
init_refs, then under
default_init_ref.
Sourcepub fn list_initial_services(&self) -> Vec<String>
pub fn list_initial_services(&self) -> Vec<String>
The names resolve_initial_references
knows without the default URL, sorted.
Sourcepub fn register_initial_reference(
&self,
name: &str,
obj: Option<&ObjectRef>,
) -> Result<(), ResolveError>
pub fn register_initial_reference( &self, name: &str, obj: Option<&ObjectRef>, ) -> Result<(), ResolveError>
CORBA::ORB::register_initial_reference: makes
resolve_initial_references
return obj for name. InvalidName if name is empty or
already an initial reference (registered or given with
-ORBInitRef), BAD_PARAM (minor
NIL_INITIAL_REFERENCE) for
a nil obj. The names a binding resolves itself, such as
RootPOA, are the binding’s to refuse.
Sourcepub fn register_local_initial_reference(
&self,
name: &str,
obj: Arc<dyn Any + Send + Sync>,
) -> Result<(), ResolveError>
pub fn register_local_initial_reference( &self, name: &str, obj: Arc<dyn Any + Send + Sync>, ) -> Result<(), ResolveError>
register_initial_reference for
an object of a binding that has no reference, such as a local
object: the ORB keeps obj under name until it is destroyed, for
resolve_local_initial_reference.
resolve_initial_references does not resolve it.
Sourcepub fn resolve_local_initial_reference(
&self,
name: &str,
) -> Option<Arc<dyn Any + Send + Sync>>
pub fn resolve_local_initial_reference( &self, name: &str, ) -> Option<Arc<dyn Any + Send + Sync>>
An object registered with
register_local_initial_reference.
Sourcepub fn root_poa(&self) -> Result<Poa, SystemException>
pub fn root_poa(&self) -> Result<Poa, SystemException>
The RootPOA. The first call starts the server side: it opens the
endpoints (INITIALIZE if one cannot be
opened) and the upcall thread pool.
Sourcepub fn register_object_key(
&self,
key: &str,
obj: &ObjectRef,
) -> Result<ObjectRef, SystemException>
pub fn register_object_key( &self, key: &str, obj: &ObjectRef, ) -> Result<ObjectRef, SystemException>
Makes obj, an object of this ORB’s POAs, answer to the simple
object key key, as in corbaloc::host:port/NameService, and
returns a reference with that key. Requests with the key are
dispatched to obj as if they had its own key: no
LOCATION_FORWARD is involved, so the reference stays valid as
long as the key is registered, also across restarts that register
it again.
BAD_PARAM if key is empty or obj is not an object of this
ORB’s POAs.
Sourcepub fn unregister_object_key(&self, key: &str)
pub fn unregister_object_key(&self, key: &str)
Removes a key registered with
register_object_key; requests with it
then raise OBJECT_NOT_EXIST.
Sourcepub fn endpoints(&self) -> Vec<(String, u16)>
pub fn endpoints(&self) -> Vec<(String, u16)>
The addresses the server side publishes in IORs, as host and port; empty until the RootPOA is used.
Sourcepub fn tls_endpoints(&self) -> Vec<(String, u16)>
pub fn tls_endpoints(&self) -> Vec<(String, u16)>
The TLS endpoints the server side publishes in IORs, as host and port; empty until the RootPOA is used.
Sourcepub fn run(&self)
pub fn run(&self)
CORBA::ORB::run: blocks until the ORB has shut down, running the
requests of MAIN_THREAD_MODEL POAs meanwhile. Other requests are
processed on the upcall threads whether or not a thread runs this.
Several threads may run it at once.
Sourcepub fn run_timeout(&self, timeout: Option<Duration>) -> bool
pub fn run_timeout(&self, timeout: Option<Duration>) -> bool
run for at most timeout (None for no limit).
Returns true when the ORB has shut down, false when the time ran
out. For a binding that must look at its own events, such as
signals, while it runs the ORB.
Sourcepub async fn run_async(&self)
pub async fn run_async(&self)
run for async code: resolves when the ORB has shut
down. It does not run MAIN_THREAD_MODEL requests, which need
run or perform_work on a
thread. With shutdown(false), the way to shut the
ORB down from async code and wait for it.
Sourcepub fn work_pending(&self) -> Result<bool, SystemException>
pub fn work_pending(&self) -> Result<bool, SystemException>
CORBA::ORB::work_pending: whether a MAIN_THREAD_MODEL request
waits for perform_work. BAD_INV_ORDER after
shutdown.
Sourcepub fn perform_work(&self) -> Result<(), SystemException>
pub fn perform_work(&self) -> Result<(), SystemException>
CORBA::ORB::perform_work: runs one waiting MAIN_THREAD_MODEL
request on the calling thread, if there is one, and returns without
waiting otherwise. For an application’s own event loop.
BAD_INV_ORDER after shutdown.
Sourcepub fn shutdown(&self, wait_for_completion: bool) -> Result<(), SystemException>
pub fn shutdown(&self, wait_for_completion: bool) -> Result<(), SystemException>
CORBA::ORB::shutdown. Refuses new invocations (BAD_INV_ORDER)
and new requests, drops the requests the POA managers hold, lets the
running ones finish and send their replies, destroys every POA, and
then closes every connection, client and server side, with
CloseConnection. Invocations still waiting for a reply fail with
COMM_FAILURE or TRANSIENT.
With wait_for_completion, returns when all that is done; called
from a servant it fails with BAD_INV_ORDER (would deadlock).
Without it, the shutdown runs on another thread and the call returns
at once, so a servant can call it and still send its reply.
Sourcepub fn destroy(&self) -> Result<(), SystemException>
pub fn destroy(&self) -> Result<(), SystemException>
CORBA::ORB::destroy: shutdown(true), and then
ends the upcall threads. Fails like shutdown(true) when called
from a servant.
Source§impl Orb
impl Orb
Sourcepub fn create_policy(
&self,
policy_type: PolicyType,
value: &Any,
) -> Result<PolicyValue, PolicyError>
pub fn create_policy( &self, policy_type: PolicyType, value: &Any, ) -> Result<PolicyValue, PolicyError>
CORBA::ORB::create_policy: a POA policy from its enumerator, or a
RelativeRoundtripTimeoutPolicy from a TimeBase::TimeT (an
unsigned long long, in units of 100 nanoseconds).
PolicyError with BAD_POLICY for a type rustorb does not know,
BAD_POLICY_TYPE when the any does not hold the policy’s type, and
BAD_POLICY_VALUE for an enumerator out of range.
Sourcepub fn set_policy_overrides(
&self,
policies: &[PolicyValue],
set_add: SetOverrideType,
) -> Result<(), SystemException>
pub fn set_policy_overrides( &self, policies: &[PolicyValue], set_add: SetOverrideType, ) -> Result<(), SystemException>
PolicyManager::set_policy_overrides of the ORB (the initial
reference ORBPolicyManager): a RelativeRoundtripTimeoutPolicy
sets call_timeout; without one (after
SET_OVERRIDE) calls have no limit. NO_PERMISSION for a POA
policy.
Sourcepub fn policy_overrides(&self, types: &[PolicyType]) -> Vec<PolicyValue>
pub fn policy_overrides(&self, types: &[PolicyType]) -> Vec<PolicyValue>
PolicyManager::get_policy_overrides of the ORB.