Go to the previous, next section.

# Using ILU with Perl

## Introduction

This document is for the Perl programmer who wishes to use ILU. The following sections will show how ILU is mapped into Perl constructs and how both Perl clients and servers are generated and built.

## The ISL Mapping to Perl

### Names

In general, ILU constructs Perl symbols from ISL names by replacing hyphens with underscores. For example, an ISL object type `T-1` would correspond to the Perl class `T_1`. Any place an ISL name appears as part or all of a Perl identifier, this translation occurs.

### Interface

Each ISL `interface` `I` generates a Perl module named `I` which, when loaded with `use I` stores information about that interface and adds hooks for client side stubs. For example, `INTERFACE map-test;` generates the Perl module `map_test` contained in the file ``map_test.pm'`.

### Basic Types

The basic ISL types have the following mapping to Perl types:

1. BYTE, BOOLEAN, SHORT CHARACTER, CHARACTER, SHORT INTEGER, INTEGER, SHORT CARDINAL, SHORT REAL, CARDINAL, and REAL all map to Perl scalars.
2. LONG INTEGER, LONG CARDINAL, and LONG REAL are not yet supported.

#### Constant

ISL constants translate to Perl subs which return the specified value. For example,

    CONSTANT pi : real = 3.14159265358979323846;

maps to

    sub pi { 3.14159265358979323846e0; }

### Strings

An ISL `SEQUENCE OF SHORT CHARACTER` maps into a Perl string. `SEQUENCE OF BYTE` is also mapped into a Perl string.

### Pickles and Typecodes (Current COPE-ish interface, may change)

A value corresponding to the ISL type `PICKLE` is an hash reference with two keys, `_type` and `_value`, where `$typecode->{_type}` is an object of the Perl class `ILU::Typecode` and `$typecode->{_value}` is the Perl form of the value.

Typecodes are represented by the Perl class `ILU::Typecode`. Typecodes are constructed with a single string argument, of the form `'interface.type'`, where interface is the ISL name for the interface, and type is the ISL name for the type. Instances of the `Typecode` class support the method

- `id()` - return the ILU type ID (CORBA repository ID) for the typecode's type.
- `name()` - return the ISL name of the typecode's type.

### Pickles and Typecodes (Possible ILU-ish interface)

A value corresponding to the ISL type `PICKLE` is an instance of the Perl class `ILU::Pickle`. Instances of this class have the following methods:

- `typecode()` - returns the typecode of the pickle's value as a string.
- `value()` - returns the Perl form of the value in the pickle.
- `bytes()` - the pickled bytes of the pickled value as a string.

The constructor for this class takes two arguments, typecode and value, and returns a new pickle containing the value specified by value of the ISL type specified by typecode. Pickles may also be created by calling the constructor with a single argument string, which must be the result of an earlier call on the `bytes()` method of another pickle instance.

Typecodes are represented by the Perl class `ILU::Typecode`. Typecodes are constructed with a single string argument, of the form `'interface.type'`, where interface is the ISL name for the interface, and type is the ISL name for the type. Instances of the `Typecode` class support the method

- `id()` - return the ILU type ID (CORBA repository ID) for the typecode's type.
- `name()` - return the ISL name of the typecode's type.

### Constructed Types

#### Enumeration

Enumarations are mapped into Perl strings that are automatically mapped into the appropriate values when marshalled and unmarshalled. (This may change).

For example, the elements

    TYPE color = ENUMERATION red, dark-blue END;

are represented in Perl by `'red'` and `'dark-blue'`.

#### Array

An ISL array maps into a Perl list with the specified number of elements. Multi-dimensional arrays map into arrays of arrays. Arrays of BYTE or SHORT CHARACTER are represented by Perl strings.

#### Sequence

An ISL sequence of short character maps into a Perl string.

All other ISL sequence types map into Perl lists. Sequences of BYTE or SHORT CHARACTER are represented as Perl strings.

#### Record

ISL records map into references Perl hashes with the same name, with the record's field names as keys.

For example, a record value of the ISL type:

    TYPE segment = RECORD left-limit : integer, right-limit : integer END;

with a left-limit of -3 and a right-limit of 7 would map to

    { left-limit => -3, right-limit => 7 }

#### Union

An ISL union maps into a Perl list reference with two components,: a discriminator, and the discriminated value. There are three possibilities:

1. If the discriminator matches one of the union case values of an arm, the second component is of the type specified by that arm.
2. If the discriminator matches no union case values and there is a default arm, the second component is of the type specified by the default arm.
3. If the discriminator matches no union case values and there is no default arm but the union has the `OTHERS` attribute, the second component is `undef`.

If the union has a default arm, then it may also be passed from Perl as a scalar of the default type.

#### Optional

A value corresponding to the ISL type `OPTIONAL T` may be `undef` (indicating the null case) in addition to the values of the type T.

### Object Types

Each ISL object type is mapped into a Perl class. These classes have the methods specified in the ISL, as well as some built-ins.

#### Surrogate and True Object Types

Both surrogate and real types inherit from `ILU::Object`. The method `ilu_true_p()` will return a true value on true instances, and a false value on surrogate instances. The string binding handle of an object instance can be retrieved with the method `ilu_sbh()`. The object-id of an instance can be retrieved with `ilu_object_id()`; it returns two values, the string server ID and a string instance-handle. If support for the CORBA `IIOP` is configured into your ILU build (in fact, this will always must be the case for Perl, at least for now), the string IOR of an instance can be retrieved by calling the method `ilu_ior()`. The type name of the most specific type of an instance can be retrieved with the method `ilu_type_name()`; the unique ID of that type can be retrieved with the method `ilu_type_id()`.

Object types which inherit from the ISL type `ilu.CORBA-Object` (which include all object types defined with OMG IDL), will inherit from the Perl class ``ILU::CORBA_Object``.

#### Methods, Parameters, and Exceptions

ISL methods of an object type map to Perl methods of the corresponding class. `IN` and `INOUT` parameters appear in the Perl method signature in the same order as they do in ISL. `INOUT` arguments are passed as references to the type of variable they would normally be mapped into, even when that type is already a reference. This is meant to avoid complicated rules about when an extra reference will be added, but it may possibly be changed in the future, so that array references (ISL array and sequence types) and hash references (ISL records) do not get the extra reference.

Let us define a result value to be either a return value (corresponding to a method's return type) or an `OUT` parameter. All result values are returned by the Perl method, with the return value (if present) appearing before any parameters.

Exceptions are implemented using the package `Error` An ISL exception translates to a Perl package whose name is that of the exception (translated as in the section Names above). These packages inherit from `ILU::Exception`, which in turn inherits from `Error`. To raise an exception, use `throw`. To catch one, use `try {} catch {}` .

For example, the declaration

    EXCEPTION division-by-zero : REAL;

in the interface `map-test` maps to the following statement in ``map_test.pm'`:

    Package map_test::division_by_zero;
    @map_test::division_by_zero::ISA = qw(ILU::Exception);

To raise this exception, use:

    throw map_test::division_by_zero ($numerator);

To catch it, use:

    try {
        $result = $calculator->divide(3/0);
    }
    catch map_test::division_by_zero with {
        print $_[0]->value," was divided by 0\n";
    };

`ASYNCHRONOUS` methods have no return values and raise no user-specified exceptions. They may return before the completion of the true method. `FUNCTIONAL` methods that have no parameters can be cached so that a surrogate address space makes only one call to the true address space to retrieve the return value.

#### Garbage Collection and COLLECTIBLE

All instances of ILU object types are covered by the normal Perl garbage collection; i.e., the application program must maintain a reference to the instance, or it will be garbage collected. With true instances of COLLECTIBLE object types, the ILU kernel will maintain an additional reference to the instance as long as it has registered clients using that instance.

## Access to standard ILU features

### Servers and Ports

Each object exported by an implementation must belong to a true server, an instance of the Perl type `ILU::Server` which is implemented by the ILU runtime. An `Server` can be created by calling
`new ILU::Server [serverID [, transport [, protocol [, objectTable]]]]`.
If serverID is a string, it specifies the server ID; if it is `undef`, one will be invented automatically. The transport argument is either a sequence of strings, chosen to be compatible with the protocol, or `undef` to let it default. The protocol argument is either a string specifying a particular RPC protocol, or `undef` to choose the default. Additional ports can be added to a server with the ``add_port()`` method, if an application needs to make it available with via multiple protocols or addresses.

The first time a true server is created, it becomes the default server. The default server is used for an exported object if a server is not otherwise specified. If an object is exported before any servers have been created, one will be created automatically using default parameters and a message to that effect will be written to stderr.

An object of type `ILU::Server` has the following methods:

- `id()` - returns the ILU server ID of the server.
- `add_port(TINFO, PINFO)` - adds another port to the server with the specified TINFO and PINFO.
- `create_serializer()` - creates and returns a serialization context.

#### Object Tables

The objectTable argument allows specification of a callback function (code reference) for creating true instances on demand. The callback function should take one argument, a string, which is the instance handle of the instance to be created, and return a true instance.

### Threading and Event Loops

To use threads, you must have configured both ILU and Perl with thread support when building them, and the thread support must be compatible. (That is, if Perl is compiled for POSIX threads, ILU must be as well. Perl FAKETHREADS will not work.) If you have done this, your ILU/Perl runtime support will be thread-capable. To have ILU begin using threads, place a call to the function `ILU->ThreadedOperation()` in your Perl program before any other ILU calls are made, and before calling `use` for any interfaces generated by the stubber. Since `use` is done at compile-time, that means the call to `ILU->ThreadedOperation()` needs to occur in a `BEGIN{}` block.

#### Animating Servers

To bring the true servers to life, run the ILU main loop by creating a new `ILU::MainLoop` and calling `$mainloop->run()`. This function does not return until `$mainloop->exit()` is called. (It is also possible to use the `ILU::Gtk` module to use the GTK main loop instead of the native ILU mainloop.)

#### Using Alarms

In order to schedule a Perl function to be called at a certain time in the future when executing the ILU main loop, an `ILU::Alarm` may be used. Objects of this type are created by calling `new ILU::Alarm()`. An `ILU::Alarm` must be set to have any effect.

The alarm's method `set(time, proc, args)` is used to set the alarm. The numeric or `ILU::FineTime` time argument is the time at which the alarm will fire; the proc argument is the Perl function that will be called when the alarm fires; and args is a list of arguments will be passed to proc.

The function `ILU::FineTime->now()` may be called to obtain ILU's idea of the current time. A value `$sec` of type in units of (possible fractional) seconds may be converted to type `ILU::FineTime` by calling `new ILU::FineTime($sec)`. Values of type `ILU::FineTime` may be compared, added, and subtracted using the appropriate overloaded arithmetic operators. These operations may be used to construct values representing any relative time (subject to precision and range limitations), which is what is needed by an alarm's `set` method.

The alarm may be set multiple times with different arguments, in which case the parameters of the most recent call to `set` are in effect. Thus, once an alarm fires, it may be reused by calling `set` again.

An alarm may be unset by calling its method `unset()`.

### Custom Records (NOT YET IMPLEMENTED)

ILU generally supports a facility named custom records. This means that an application can declare that the language-specific mapping of a particular record type ISL(A) to lang(A) is to be overridden, and that instead a specific type X will be used in this language to represent values of ISL(A). In Perl, this is done by simply replacing the generated class definition with a different class definition.

For example, suppose we had the ISL record type

    INTERFACE Ifc;
      ...
    TYPE Foo = RECORD color : RGB-tuple, position : XY-pair END;

The normal mapping of `Ifc.Foo` to Perl would be to a hash reference with two keys (`color`, and `position`. To override this, simply define a new class `MyFoo` in your application that is implemented as a blessed reference to an array including these keys which has a method `ilu_record_init`. Then call `ILU->RegisterCustomRecord( 'Ifc.Foo' => 'MyFoo')`. Subsequently, whenever an `Ifc.Foo` is unmarshalled, it will be blessed into `MyFoo` and `$rcd->ilu_record_init()` will be called. (It might be nice to additionally allow such custom records to have getters and setters for their attributes.)

### String Binding Handle Formation

To use object tables properly, it is usually necessary for a client program to create a surrogate instance for which the true instance does not yet exist. In Perl, this is done by creating a string binding handle for the object, then calling ``ILU->ObjectOfSBH()`` on that SBH. String binding handles may be formed by calling the function ``ILU->FormSBH()``.

### Simple Binding

A true instance may be published with the simple binding service by calling its method `ilu_publish()`. A true instance may be unpublished by calling its method `ilu_withdraw()`.

A published ILU object may be obtained by calling `ILU->LookupObject(sid, ih, cl)`, where `sid` is object's server's server ID, `ih` is the object's instance handle, and `cl` is its class.

### Principal Identities and Passports

An ILU passport (see section Security) is represented in Perl by an instance of the ``ILU::Passport`` object type. Instances of this type can be obtained by calling ``new ILU::Passport()``. Please see the documentation of that function for more information on the abilities of this object type.

The passport of the caller may be obtained in the true method by calling the ILU runtime routine `ILU->CallerIdentity()`. The `native' passport may be obtained by calling ``ILU->GetPassport()``. In the case of a local call, these two passports may be the same object. Passports are thread-local; that is, an application may use a different passport in each thread.

## Building Perl/ILU Applications

### Stub Generation

To generate the Perl stubs from an ISL file, use the program `perl-stubber`. The file ``name.pm'` is generated from each ISL `INTERFACE name`.

In the future, it may be possible to have the information in ``name.pm'` generated dynamically when needed, without running the stubber separately.

### Implementing an ILU module in Perl

A Perl package that implements ILU objects of type T defined in `INTERFACE I` inherits from `I::T`. If there is inheritance in the ISL, and an implementation of a subtype wants to inherit from an implementation of a supertype, the base class must be appear in `@ISA` before `I::T`.

The constructor for the true object must call `$self->ilu_init([server[,handle[,implements]]])`. If server is present, it specifies the server to which this object belongs, otherwise, a default value is used. If handle is present, it is used as the instance handle, otherwise one is invented. implements is only needed when, due to implementation inheritance, the implementation class is derived not only from the class it implements, but also from a base class of that class.

For example, objects for the ISL

    INTERFACE j;

    TYPE c1 = OBJECT METHODS one() END;
    TYPE c2 = OBJECT METHODS two() END;
    TYPE c3 = OBJECT SUPERTYPES c1, c2 END METHODS three() END;

could be implemented in Perl by

    use ILU;
    use J;

    package C1;
    @C1::ISA = qw(J::c1);

    sub new {
       my ($class, $server, $ih) = @_;
       my $self = bless {};

       ... initialization ...

       $self->ilu_init($server, $ih);
    }

    sub one {
       ...
    }

    package C2;
    @C2::ISA = qw(J::c1);

    sub new {
      ...
    }

    sub two {
      ...
    }

    package C3;
    @C3::ISA = qw(C1 C2 J::c3);

    sub new {
       my ($class, $server, $ih) = @_;
       my $self = bless {};

       $self->ilu_init($server, $ih, 'J::c3');
    }

In this case `C3`'s method `one` is implemented by `C1::one` and `C3`'s method `two` is implemented by `C2::two`.

#### Exporting Objects

An object can be exported in one of three ways:

1. The object's string binding handle may be obtained by calling its method `ilu_sbh()` and communicating this somehow to a client, who then turns the handle back into an object by calling `ILU->ObjectOfSBH(cl, sbh)`.
2. The object may be published using the simple binding service by calling its method `ilu_publish()`. In order for this to be effective, the object must have a well-known object ID, or the object ID must be communicated to clients, so clients can know what to pass to `ILU->LookupObject`. The object ID is the combination of the object's instance handle and its server's server ID.
3. The object may be returned by a method or passed back in a method's `INOUT` or `OUT` parameter.

### Using an ILU module in Perl

The ILU runtime interface is in the Perl module `ILU`. Perl definitions for ISL `INTERFACE I` are in the Perl module `I`. As with any other modules in Perl, the functionality in this module is added to your program using the `use` statement.

A client program may create an ILU object in one of three ways:

1. Knowing the string binding handle `sbh` and class `cl` of an object, call `ILU->ObjectOfSBH(cl, sbh)` which returns an instance of that class. For example, to obtain an instance of ISL type `Square` from `INTERFACE Shapes` whose string binding handle is `$sbh`, one would call `ILU->ObjectOfSBH('Shapes::Square', $sbh)`.
2. Knowing the object ID `(sid, ih)` and class `cl` of an object that has been published using the simple binding service, call `ILU->LookupObject(sid, ih, cl)` which returns an instance of that class (or `undef` if the lookup fails).
3. Receive an instance as a result value from a method call that returns an object type or has an object type as an `INOUT` or `OUT` parameter.

### CORBA Support in Perl

Perl `CORBA` module contains support for the classes ``CORBA::ORB`` and ``CORBA::Object``, and the ``CORBA::ORB_init()`` function, which provide some compatability with the standard CORBA interfaces. See the Perl/ILU API Reference for more information on these classes.

## Perl/ILU API Reference

### Identifiers in Module `ILU`

The following functions are meant to be called as `ILU->TheFunction(args)`. That is, they take an extra first argument which is ignored, allowing the use of the method invocation syntax. (This may be changed in the future.)

Function: CallerIdentity ()

Returns the passport containing identities of the caller. This routine is only valid inside the code of a true method.

Function: DoSoon (FUNCTION, ARGS-TUPLE, STRING-DESCRIPTION)

Causes the function FUNCTION to be run with args ARGS-TUPLE to be run at some point in the future, when the system finds it to be convenient. In the threaded world, a new thread is forked to run the function; in the non-threaded world, the function is executed at some point by the event loop as a background task.

Constant: FALSE

A value which evaluates to Perl boolean False.

Function: FormSBH (sid, ih, type, pinfo, ...)

Forms a valid ILU string binding handle from the arguments and returns it. The sid and ih arguments are strings containing the server ID and instance handle for the desired instance. The type argument should be the Perl class for the most specific object type of the desired object. The pinfo is a string containing the protocol information describing the object implementation's preferred communication protocol. The remaining arguments are strings specifying the transport stack needed to connect to the implementation. The elements of the protocol and transport info strings are separated by underscores.

For instance, to create a string binding handle for an instance of type `Foo.Bar`, with server id `"some-server-id"` and instance handle `"some-instance-handle"`, exported via `Sun RPC`, version 2, with program number 1000007, version 3, via `TCP/IP` from host `"foobar.somewhere.com"`, port 3456, we'd say
`sbh = ILU->FormSBH('some-server-id', 'some-instance-handle','Foo::Bar',
'sunrpc_2_1000007_3, 'sunrpcrm', 'tcp_foobar_somewhere_com_3456')`
Note that use of this procedure requires some specialized knowledge, such as knowing that use of `Sun RPC` also requires use of the `Sun RPC` record-marking transport layer when used over `TCP/IP`.

Constant: FineTimeRate

The precision of type `ilu_FineTime` in seconds is the reciprocal of this constant.

Function: GetPassport ()

Returns the current passport for this thread. See also ``SetPassport()``.

Function: GetPipeline ()

Returns the current pipeline context for this thread. See also ``CreatePipeline()`` and ``SetPipeline()``.

Function: GetSerializer ()

Returns the current serialization context for this thread. See also the ``createSerializer()`` method on the ``ilu_Server`` class, and the ``SetSerializer()`` function.

Function: LookupObject (sid, ih, cl)

Returns the object with object server ID sid, object instance handle ih, and Perl package name `cl`, assuming it was previously published using the simple binding service. If the lookup fails, `None` is returned.

Function: ObjectOfSBH (cl, sbh)

Returns the object corresponding to the Perl package name cl and string binding handle sbh.

Function: ParseSBH (sbh)

Returns the the object id and contact info corresponding to the string binding handle sbh as a list `(ih, sid, mstid, cinfo)`. ih is instance handle, sid the server ID, mstid the most specific type id and cinfo the contact info encoded as a string.

Function: RegisterCustomSurrogate (class)

NOT YET IMPLEMENTED

Registers class as the object type to create when receiving a surrogate of the type indicated by the `_IluClass` field of class. class must be a subtype of the default surrogate type for this ILU type. This allows custom surrogates, with implications for caching and other object-type-specific functions.

Function: RegisterInputHandler (fileno, handler_fn, ...)

Sets up handler_fn to be called every time input is availabe on the file corresponding to fileno. (You can get the file number of a file handle with `fileno(HANDLE)`. handler_fn is a reference to a subroutine or anonymous subroutine. This is useful for implementing a server that also responds to commands typed to its standard input, for example. Passing a value of `undef` for the handler_fn removes the handler. Any additional arguments will be passed to the handler function

Function: SetCalloutExceptionHandler (handler-fn)

NOT YET IMPLEMENTED

This function can be used to define a function handler-fn which is called when an internal Perl exception is signalled in code called from the ILU C code. The handler function receives four arguments: a string indicating where in the ILU runtime the exception was encountered, the exception type, the exception value, and a traceback object. This function is typically used to note the exception to a file or stderr; see the example usage in ``ILUSRC/runtime/python/iluRt.py'`. If a parameter of `None` is passed to `SetCalloutExceptionHandler`, it cancels any handler function in use, and a default built-in one is used.

Function: SetDebugLevel (flags)

Sets the ILU kernel debugging flags according to its argumentSee the Debugging section of the ILU Manual for more information on the argument.

Function: SetDebugLevelViaString (switches)

Sets the ILU kernel debugging flags according to its argument, which is a colon-separated list of debug switches.See the Debugging section of the ILU Manual for more information on these switches.

Function: SetPassport (passport)

Sets the current passport identity for this thread, and returns the passport active before this call. Either of these can be `None`. Also see the function ``CreatePassport``, and the function ``GetPassport``.

Function: SetPipeline (pipeline)

Sets the current pipelining context for this thread, and returns the context active before this call. Either of these can be `None`. Also see the function ``CreatePipeline``, and the function ``GetPipeline``.

Function: SetSerializer (serializer)

Sets the current serialization context for this thread, and returns the context active before this call. Either of these can be `None`. Also see the ``createSerializer`` method on the class ``ilu_Server``, and the function ``GetSerializer``.

Function: ThreadedOperation ()

Enables thread use in both the ILU kernel and the ILU/Perl runtime. This routine should be called in a begin block before calling `use` for any stubber-created modules, and before any other ILU calls are made.

Constant: Version

The ILU version string.

Class: Object (ILU::MainLoop)

A type representing an ILU server. It supports the following methods:

- `new ()` - creates a new object of type `ILU::MainLoop`
- `run ()` - Runs the loop
- `exit ()` - Causes the specified loop to exit.

Class: Object (ILU::Server)

A type representing an ILU server. It supports the following methods:

- `default ILU::Server ()` - returns the default server.
- `new ILU::Server( [serverID [transport [protocol [objtable]]]] )`

  Create an `ILU::Server` object with the specified serverID, transport, and protocol. If serverID is unspecified or `undef`, an identifier will be invented automatically. If transport or protocol are unspecified or `undef`, they will default to `['sunrpcrm', 'tcp_0_0']` and `'sunrpc'`, respectively. (Other combinations that would work are transport of `['tcp_0_0']` and protocol of `'iiop_1_0_1'`, transport of `['sunrpcrm', 'tcp_0_0']` and protocol of `'courier'`, and transport of `['tcp_0_0']` and protocol of `'http'`, depending on the configuration of your ILU system.) The first time a server is created, the server so created becomes the default server. If there is no default server when one is required, one will be created using default parameters and a message will be issued on stderr. The objtable argument allows specification of a callback function for creating true instances on demand. The callback function should take one argument, a string, which is the object ID of the instance to be created, and return a true instance.

- ``add_port (TRANSPORT, PROTOCOL)`` - adds a port with the specified TRANSPORT and PROTOCOL (described above) to the server instance.
- ``id ()`` - returns the string identifier of the server.

Class: Object (ILU::Passport)

The ``ILU::Passport`` object is used to provide a sense of identity in the ILU system. It can hold any number of different identities, each of which is represented with an appropriate data structure that varies from identity type to identity type.

The ``ILU::Passport`` object type has the following methods:

- ``new`` - creates and returns an empty passport.

- ``lookupIdentity (IDENTITY-TYPE-NAME)`` - returns the data structure for the specified identity, if the passport contains one; Returns `None` otherwise. Raises `ilu.IluGeneralError` if the named identity type does not exist. The identity type ``'ConnectionIdentity'`` is always supported; the identity type ``'SunRPCAuthUnixIdentity'`` will be supported if support for the `sunrpc` protocol has been configured into ILU.
- ``addSunRPCAuthUnix (HOSTNAME, UID, GID, GROUPS)`` - adds an identity of type ``'SunRPCAuthUnixIdentity'`` to the passport with the specified HOSTNAME, UID, GID, and GROUPS (the remaining parameters). See Appendix A of RFC 1831 at `http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1831.txt` for details on the meaning of these parameters. This method will only be available if support for the `sunrpc` protocol has been configured into ILU.

Class: Object (ILU::Pipeline)

The ``ilu_Pipeline`` object is used to allow multiple requests to be outstanding on non-concurrent protocol streams.

The ``ILU::Pipeline`` object type has the following method:

- ``new`` - creates and returns a pipeline object.

Class: Object (ILU::Serializer)

The ``ilu_Serializer`` object is used to ensure that multiple requests are received by the server in the same order that the client makes them.

The ``ILU::Serializer`` object type has the following method:

- ``new`` - creates and returns a serializer object.

### Identifiers from the `CORBA` Module

Variable: %CORBA::InitialReferences

A hash with string keys, and values of type ``CORBA::Object``. It is used to resolve strings passed as parameters to ``CORBA::ORB::resolve_initial_references()``. The following names are supported automatically by Perl runtime:

- NameService
  If the environment variable `ILU_COS_NAMING_IOR` is bound to a string IOR for a OMG IDL `CosNaming::NamingContext` object instance, the Perl runtime will attempt to create a surrogate for that instance locally, ping it, and if successful will bind it to the string `"NameService"`.

Class: Object (CORBA::Object)

A type which all object types defined in OMG IDL, or inheriting from `ilu.CORBA-Object` in ISL, participate in. It supports the following methods:

- `_is_a(type_uid)` - returns `True` if the object is of the specified type, `False` otherwise; raises `ILU::IluUnknownTypeIDError` if the type_uid is unknown in this address space;
- `_is_nil()` - returns `False`; raises `TypeError` if called via ``Corba::Object::_is_nil()`` on a non-Perl-object type;
- `_non_existent()` - returns the logical inverse of the result of calling `ilu.PingObject()` on the object;
- `_is_equivalent(other)` - returns the result of comparing self and other with the Perl `==` operator;
- `_duplicate()` - does nothing, returns self;
- `_release()` - does nothing, returns nothing;
- `_hash(max_value)` - returns `(hash(self) % (max_value + 1))`;
- `_get_implementation()` - raises ``IluUnimplementedMethodError``;
- `_get_interface()` - raises ``IluUnimplementedMethodError``;

The ``CORBA::Object`` class is actually implemented in ``ILU::CORBA_Object``, so all classes which inherit from ``ILU::CORBA_Object`` will have access to these methods.

Class: ORB

The general class for manipulating the object request broker. There is typically only one instance of this class per address space. It is retrieved with the function ``CORBA::ORB_init()``; it supports the following methods:

- `object_to_string(instance)` - returns a string which can be used in a subsequent ``string_to_object()`` call;
- `string_to_object(string)` - if the specified string is well formed and specifies an object, the object is created locally and a reference is returned; the reference may be to a true instance if the string names a true instance; if the string is poorly formed, the Perl exception ``ilu.IluGeneralError`` is raised. This method does not test for the existence of the instance.
- `resolve_initial_references(string)` - If the string argument is bound in the dictionary ``%CORBA::InitialReferences``, the value is returned. Otherwise, the exception ``CORBA::InvalidName`` is raised. See the documentation of ``%CORBA::InitialReferences`` for a listing of the names that are bound automatically, if any.

Function: ORB_init (argv=(), orb_id='ilu')

Returns an instance of ``CORBA::ORB`` with the specified orb_id (currently only the ORB ID `'ilu'` is supported). The arguments which may be passed in via argv are ignored.

### Methods and Attributes of ILU Objects

- `ilu_object_id()` returns the object ID of the object.
- `ilu_publish()` publishes the object using the simple binding service.
- `ilu_sbh()` returns the object's string binding handle.
- `ilu_type_id()` returns the unique type identifier of the object's ILU type.
- `ilu_type_name()` returns the type name of the object's ILU type.
- `ilu_withdraw()` undoes the effect of ilu_publish().

Go to the previous, next section.