next up previous contents index
Next: Conclusion Up: libIntegra: a system for Previous: IXD (Integra eXtensible Data)   Contents   Index


(Integra)tion via the library

libIntegra is a cross-platform shared library, mostly written in ISO C89 compliant C, and packaged using the GNU autotools tool chain. It consists of a common API, and a number of optional components. The library is hosted on Sourceforge.net6 where source code and API documentation can be accessed.

Data persistence

For persistent storage of module data and other data relating to musical works we have designed and configured an on-line database. The only way in which users may add new, or edit existing module definitions is via a web-based interface to this database. The database makes use of the libIntegra serialization component to generate XML files on-the-fly, and these files are bundled into a gzipped archive to be downloaded and stored locally for potential offline use. Any program linked to libIntegra can then use the same XML handling functions to de-serialise the data, and form an in-memory representation of it.

Instance host

As well as a serialization component the library provides an instance host, which is responsible for keeping a record of each module's run-time state. This includes the values that any of its ports have, and any connections that are made between modules. The instance host acts as an OSC server (using the liblo library7), and operations can be performed on modules by sending OSC messages to it. The instance host supports a condensed OSC syntax for loading, removing, connecting, disconnecting and addressing modules. For example two module ports can be connected with the following message:

/connect <module id> <port id> 
         <module id> <port id>

Module instances can either communicate with each other through the instance host using OSC, or using an environment-specific messaging system. When messages pass through the Instance host, various operations can be performed on the data that passes through. These operations include type checking, range checking, unit conversion and type conversion. All of these can be validated against the module definition held in memory.

Library/target bridge

In order to instantiate modules in a target environment and to communicate directly with these modules, a target-specific 'bridge' is required. The 'bridge' is a dynamically loaded, binary shared object hosted 'inside' the instance host. Its purpose is to facilitate bi-directional communication between the instance host and a given target module host (see [*]). The library provides a very simple API that each target-specific bridge must conform to. The instance host has no knowledge of the software being used to host module instances so the bridge acts like a translator receiving function calls, and performing the relevant target-specific actions. These actions include instantiating modules, removing them and connecting them. Most OSC commands supported by the Instance host have a corresponding function in the bridge.

It is the bridge's software-specific communication mechanism that determines the protocol used to construct module implementations. It is possible, although not necessarily desirable to have several bridges for a given target, each of which elicits a different approach to module construction. This might be useful for compatibility with existing modularisation efforts, such as the Jamoma project or Faust's auto-generated PD abstractions.

Figure: A model of the parts constituting libIntegra and how the library interfaces with other parts of the system.

Module host

The module host is any software that hosts Integra modules: it is not part of libIntegra. Typically, a module host will be dynamically linked to libIntegra at compile time. At run time the module host can make direct calls to functions in the instance host and also make use of the Instance host OSC interface. Typically the OSC interface is used for communication with modules or hosts that are running in a different program or operating system process. Communication from the Instance host to the module host and modules is always achieved through the 'bridge'.

It is also possible for the module host to be a standalone application that doesn't link to libIntegra. In this case the bridge will usually use a network-based protocol such as OSC to communicate with the module host. A Unix pipe or socket is another possibility for this type of setup.

Inter-library communication

An arbitrary number of libIntegra instances may be running on the same computer or on any number of networked computers. Each libIntegra instance can be running in a new instance of a common module host, or a completely different module host. A single computer setup is shown in Figure [*].

When multiple libIntegra instances are used, only one (the master), can make use of the serialization layer to load and save Integra module instance data and collections. This is to prevent several versions of the same collection being opened by different library instances, and becoming unsynchronised. If the user or developer knows that the serialization layer will not be required, the library can be compiled without it.

The Instance host contains mechanisms for inter-library communication and auto-discovery. This is mostly achieved through OSC messaging, and facilitates the loading of Integra collections across several module hosts, with transparent state saving.

next up previous contents index
Next: Conclusion Up: libIntegra: a system for Previous: IXD (Integra eXtensible Data)   Contents   Index
Jamie Bullock, Henrik Frisk