Skip to main content

rustorb_core/
lib.rs

1//! ORB core: connection management, request dispatch and the POA.
2//!
3//! Network I/O runs on an internal multi-threaded tokio runtime, and
4//! servants are invoked on a separate pool of long-lived ORB threads.
5//! The public API is synchronous.
6//!
7//! The client side:
8//!
9//! - [`Orb`] owns the runtime and a pool of GIOP connections, one per
10//!   server endpoint. [`Orb::string_to_object`] accepts stringified IORs,
11//!   `corbaloc:` and `corbaname:` URLs, and
12//!   [`Orb::resolve_initial_references`] the
13//!   `-ORBInitRef` / `-ORBDefaultInitRef` options.
14//! - [`ObjectRef::request`] builds a request whose arguments are written to
15//!   an [`OutStream`]; [`Request::invoke`] returns a [`Reply`] to read with
16//!   an [`InStream`], or an [`Exception`]. Requests use GIOP 1.0 to 1.2 as
17//!   the target's profile allows, follow `LOCATION_FORWARD`, answer
18//!   `NEEDS_ADDRESSING_MODE`, try alternate addresses, and are sent again
19//!   after a `CloseConnection` from the server.
20//! - [`name`] has the CosNaming name type and its string form, used for
21//!   `corbaname:` and by the naming service client in `rustorb-naming`.
22//! - [`TypeCode`] describes IDL types, and [`Any`] holds a [`Value`] of
23//!   any type; [`OutStream::write_any`] and [`InStream::read_any`] marshal
24//!   them, and [`OutStream::write_value`] / [`InStream::read_value`]
25//!   marshal any value as its TypeCode says.
26//! - [`CodeSets`] negotiates the transmission code sets from the IOR and
27//!   converts `string` data; rustorb's native code sets are UTF-8 and
28//!   UTF-16.
29//!
30//! The server side, started by [`Orb::root_poa`]:
31//!
32//! - The ORB listens on [`OrbOptions::endpoints`] and answers GIOP 1.0 to
33//!   1.2 requests in the version they came in.
34//! - [`Poa`] is the RootPOA and the POAs created under it, with their
35//!   [`Policy`] values, active object maps and [`PoaManager`]s. Object keys
36//!   of PERSISTENT POAs have omniORB's format, so references survive a
37//!   switch between the two.
38//! - A [`Servant`] reads its arguments from an [`InStream`] and writes the
39//!   result or a user exception to a [`ServerReply`]. Servants run on a
40//!   pool of long-lived upcall threads, never on the I/O threads, and
41//!   requests of one connection run in parallel. SINGLE_THREAD_MODEL POAs
42//!   run their requests one at a time, and MAIN_THREAD_MODEL ones on the
43//!   thread in [`Orb::run`] or [`Orb::perform_work`].
44//! - Objects not in the active object map can be served by a default
45//!   servant, a [`ServantActivator`] or a [`ServantLocator`], and child
46//!   POAs created on demand by an [`AdapterActivator`]. [`PoaCurrent`]
47//!   tells a servant which object a request is for.
48//! - Calls to objects of the same ORB do not use the network: the request
49//!   is marshalled and dispatched on the calling thread.
50//! - [`Orb::run`] waits for [`Orb::shutdown`], which finishes the running
51//!   requests and closes every connection with `CloseConnection`.
52//!
53//! What the ORB does (connections, requests, exceptions, forwards, GIOP
54//! messages) is reported as [`tracing`](https://docs.rs/tracing) events;
55//! without a subscriber, `-ORBtraceLevel` writes them to standard error.
56//! See [`trace`].
57
58mod codeset;
59mod connection;
60pub mod dii;
61pub mod dynany;
62mod exception;
63mod fixed;
64pub mod idl;
65mod idle;
66pub mod iop;
67pub mod name;
68mod object;
69mod orb;
70pub mod pi;
71mod poa;
72pub mod policy;
73mod pool;
74mod servant;
75mod server;
76mod stream;
77mod timeout;
78mod tls;
79pub mod trace;
80pub mod typecode;
81mod value;
82mod wire;
83
84pub use codeset::CodeSets;
85pub use dynany::{DynAny, DynAnyError, DynAnyFactory};
86pub use exception::{
87    Exception, OMG_VMCID, SystemException, SystemExceptionKind, UserException, minor,
88};
89pub use fixed::{Fixed, ParseFixedError};
90pub use object::{AsyncRequest, CallbackRequest, ObjectRef, Reply, Request};
91pub use orb::{ClientAuth, EndpointAddr, Orb, OrbOptions, ResolveError, TlsOptions};
92pub use poa::{
93    Bidirectional, IdAssignment, IdUniqueness, ImplicitActivation, Lifespan, ObjectId, Poa,
94    PoaCurrent, PoaError, PoaManager, PoaManagerState, Policies, Policy, RequestProcessing,
95    ServantRetention, ThreadPolicy,
96};
97pub use policy::{PolicyError, PolicyType, PolicyValue, SetOverrideType};
98pub use rustorb_cdr as cdr;
99pub use rustorb_cdr::{LongDouble, Octets};
100pub use rustorb_giop as giop;
101pub use rustorb_giop::CompletionStatus;
102pub use servant::{
103    AdapterActivator, Cookie, Servant, ServantActivator, ServantLocator, ServantManager,
104    ServantManagerError, ServerReply,
105};
106pub use stream::{InStream, OutStream};
107pub use timeout::{set_thread_call_timeout, thread_call_timeout};
108pub use typecode::{TCKind, TypeCode, TypeCodeError};
109pub use value::{
110    Any, CustomReader, Native, Value, ValueRef, ValueTypeResolver, lookup_value_type,
111    register_custom_reader, register_value_type, set_value_type_resolver, unregister_custom_reader,
112    unregister_value_type,
113};