Re: Questions - 1st pass at a FAQ

[Michael Meeks <michael ximian com>]

Hi Jonathan,

On Wed, 24 Oct 2001, Jonathan Bartlett wrote:
> 1) Where is the feature list for ORBit2?  The one referenced by
> orbit-resource isn't available.

        Ahh :-) ok - I've just written an ORBit2 FAQ - I've no idea who
maintains what website - but ... this is accurate and up-to date. I append
it.

> 2) How do you make use of shared-library CORBA servers?  How do you
> build them and how do you connect with them?

        Essentialy you probably want to look at bonobo-activation and the
libbonobo platform in Gnome 2.0 ( you'll need HEAD glib for that ).

        The fast shlib mode is based on the reference being in-proc.

> 3) Is there any documentation on how to effectively use Servants, the
> POA, and POAManagers?  Hopefully with C code, too.  What is the best
> reference for this?

        A very good book is Henning & Vinoski's CORBA programming thing, I
forget the exact title :-) alternatively read the specs available at
http://www.omg.org/

> Sorry for the questions.  I've been looking through the web trying to
> find this info, so I thought I'd post to this list.

        Heh, that's fine, you kicked me into writing a start of a FAQ.

        Regards,

                Michael.

The ORBit2 FAQ - v 0.1
  Michael Meeks (michael@ximian.com)


* What is ORBit2 ?

	ORBit2 is the next revision in the ORBit development plan. It
is substantialy re-written, and contains a number of new, advanced
features. One of these is an abstract IO layer split out into the
separate 'linc' library. This allows features such as SSL operation
and multiple new connection types.


* Who is responsible ?

        The bulk of the initial work is down to Elliot Lee, and
various people whose ideas he fused liberaly Kennard White, Sebastian
Wilhelmi - the polishing and recent work down to Mark McLoughlin,
Martin Baulig and myself.


* How is ORBit2 better than ORBit 'stable' ?

In many ways:

        + Targets CORBA 2.4 instead of CORBA 2.2
        + Theoreticaly thread safe - see later.
        + In conjunction with linc allows all manner of new transports
        + Protection against malicious / badly formed wire data
        + Type centric
		+ smaller - stubs / skels are tiny: ~50% smaller.
		+ generic operation, eg. method tracing
		+ fast in-proc language bindings
		+ marginaly slower currently.
        + Uses glib mainloop
        + "URL for IOR" to allow retrieving an IOR via HTTP
        + Cleaner
		+ lots of code cleaning and re-factoring
		+ most CORBA interfaces generated from pseudo-IDL
		+ a more pleasant directory structure
		+ more complete implementations of many things
        + Tested - fairly comprehensive stress testing.
	+ No resource leakage of TypeCodes
        + Lots of bugs fixed, and new ones created.


* Is ORBit2 thread safe ?

	ORBit2 is theoreticaly thread safe, ie. we thought about it a
bit during the design - which is nominaly thread safe, we added a lot
of locks, and we fixed deadlocks when they were found. It has yet to
be tested in anger in a multi-threaded environment.

** What is this re-enterancy thing ?

	When a method is invoked, while the ORB is waiting for a
return value or exception (if applicable) the ORB processes any other
incoming requests in a re-enterant fashion. This occurs even during
threaded operation currently.

** Can I invoke methods from multiple threads ?

	Yes, this should present no particular problem.

** Can I receive invocations in multiple threads ?

	Yes - assuming you have a glib mainloop ( or a linc_mainloop )
running in one or several of your threads. The precice thread that the
invocation is recieved in is unpredictable.

** Can I have each invocation handled by a different thread ?

	Currently no - there is tentative compile time support in the
ORB for this mode of operation, but currently no effort has been put
into this. If the compile time support for this is enabled, the
mainloop and re-enterant processing is disabled.


* How does the new 'type' system work ?

	The new type system forms a fundamental part of ORBit2 and
presents a major simplification.

** What do you mean by 'type' data ?

	By type data we mean not only structure layout information,
but also full interface and method information. ie. not just value
class types but interfaces as well.

** How do we get type data for an interface ?

	There are two answers to this. Firstly, if you have a pointer
to an Object reference and you know nothing more than that it is a
ORBit2 handled CORBA object, you can (via. an ORBit2 extension)
request it's type id, and from this, a full interface description.

	see ORBit2/include/orb/orb-core/orbit-small.h
	and ORBit2/include/orb/orb-core/orbit-iinterface.h (from)
	    ORBit2/src/orb/orb-core/orbit-iinterface.idl

*** Type data from an object reference ?

	CORBA_char *type_id;
	ORBit_IInterface *iface;

	type_id = ORBit_small_get_type_id (obj, ev);
	iface   = ORBit_small_get_iinterface (obj, type_id, ev);

*** Type data from a type library ?

	If we wish to implement an interface in our scripting language
that is not currently registered with the ORB, then we can load it
dynamicaly from the type library interface:

	ORBit_small_load_typelib ("Bonobo");

	We can then suck all the interface and TypeCode information
out of the library, in order to construct local language bound peers:

CORBA_sequence_CORBA_TypeCode   *ORBit_small_get_types ("Bonobo");
CORBA_sequence_ORBit_IInterface *ORBit_small_get_iinterfaces (...);

** What is a type library (or imodule) ?

	Type libraries are essentialy the same generic interface
information that the ORB uses to marshal and de-marshal information in
the C stubs. It is contained in the -common.c file of a compiled set.

	To install a type library correctly you need to have some
automake a little like:

orbittypelib_LTLIBRARIES = Bonobo_module.la
orbittypelibdir = $(libdir)/orbit-2.0
IMODULE_SOURCE =	\
	Bonobo.h	\
	Bonobo-common.c	\
	Bonobo-imodule.c
Bonobo_module_la_SOURCES = \
	Bonobo-imodule.c
Bonobo_module_la_LIBADD = \
	$(LIBBONOBO_LIBS)
Bonobo_module_la_LDFLAGS = \
	-export-dynamic -module

$(IMODULE_SOURCE): $(idl_DATA) $(ORBIT_IDL)
	$(ORBIT_IDL) $(idl_flags) --imodule \
		     $(top_srcdir)/idl/Bonobo.idl

	Note that the library is installed into $(libdir)/orbit-2.0.
When a typelib is loaded, an explicit path can be passed in, otherwise
the ':' delimited path environment variables ORBIT_TYPELIB_PATH and
GNOME_PATH are searched.

** How do I find what type libraries are installed ?

	There is a utility ORBit2/test/typelib-dump that will display
a list of available libraries for your path setup:

	Installed type libraries:

	/opt/ngnome2/lib/orbit:

		Everything
		Accessibility
		Bonobo

	It can also rudimantarily dump the contents of a type library.

** Why bother generating type information from an interface ?

	With ORBit stable, language bindings had to load and parse the
IDL definitions for the interface. This had several disadvantages.

	+ Primarily performance - loading a load of IDL text, forking
the pre-preocessor to pre-process it, resolving all the symbols as
strings, converting to an internal representaton - took time. With a
standard internal representation, and a simple dlopen to grab it we
have a major performance win.

	+ Include problems: many IDL files are grouped into a single
file to build, and can cause grief when included individualy. This
contrasts with a working bundle of interfaces, verified at package IDL
compile time.

	+ libIDL - is an unmaintained mess, and is not particularly
pleasant to link against, or code to.

	+ Finding the IDL files - there was no standard path
structure, or method of reliably locating all the relevant IDL files.
Now at least there is an ad-hoc shared standard.

** Why is a type based ORB better ?

	Firstly ABI reduction, in ORBit stable the API usage by the
stubs was very considerable - many methods were called, and there was
a considerable body of code in a stub or a skel.

	With ORBit2 a stub looks like a bit like this:

Bonobo_Unknown
Bonobo_Unknown_queryInterface (Bonobo_Unknown     obj,
                               const CORBA_char  *repoid,
                               CORBA_Environment *ev)
{
        Bonobo_Unknown _ORBIT_retval;

        ... local fast case ... else ...
        { /* remote marshal */
                gpointer _args[] = {
                        (gpointer) & repoid
                };

                ORBit_small_invoke_stub (
                        obj,
			&Bonobo_Unknown__iinterface.methods._buffer[2],
			&_ORBIT_retval, _args, NULL, ev);

        }

        return _ORBIT_retval;
}

	ie. we expose a single method call here
'ORBit_small_invoke_stub'. This method is passed the object reference,
the arguments in a normalized form ( as an array of gpointers ) a
pointer to the return value, any CORBA_Context we might be using and
the exception environent.

	The skeleton is similar, unwinding a gpointer array of
arguments and invoking the C method. NB. for language bindings, you
can hook the a virtual invocation pointer on the servant to recieve a
method type data pointer and handle the invocation fully yourself.

	The indirection and allocation semantics of the argument
passing, as well as the C CORBA semantics are lucidly documented in
ORBit2/docs/internals/interface-indirection.gnumeric.

** Why is a type based ORB potentialy faster ?

	Well - partly due to encapsulation. Encapsulation often
carries a cost; in ORBit stable there are several layers. Even though
the stubs and skels are substantialy unrolled, there are a
considerable amount of method calls, and lots of wasteful indirection.

	In ORBit2 we can hide an _extremely_ optimized, top to bottom
to the wire generic marshaler behind ORBit_small_invoke_stub. This
would be totaly private to the ORB, maintaining ORB encapsulation, but
giving us buckets of room for optimization.

	Secondarily, in ORBit stable the stubs and skels are massively
unrolled, giving not only a size penalty but also a speed penalty in
terms of the processors instruction cache (Icache). In contrast ORBit2
maintains a far smaller Icached working set, since the generated code
that is different per method is tiny, and the same generic code is
executed to do the marshaling for each method.

	Hence - although currently what performance tests we have
suggest that ORBit2 is ~20% slower than ORBit stable, it will be
possible ( in a totaly binary compatible fashion ) to tweak and
optimize the marshal / de-marshal process to make it arbitarily fast.



-- 
 mmeeks@gnu.org  <><, Pseudo Engineer, itinerant idiot