next up previous contents index
Next: Use case scenario Up: libIntegra: a system for Previous: Database   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.

Serialization component

As mentioned in [*] the database also makes use of the serialization component. When the user requests a particular module collection, the database is queried for the relevant data, and the serialization library component is used to generate a number of XML files. These files are in turn bundled into a gzipped archive and stored locally. The program linked to the Integra library can then use the same XML handling functions to de-serialize 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 library11), and operations can be performed on modules by sending OSC messages to it. The instance host supports a simple efficient syntax as shown in table [*].

Module instances can either communicate with each other through the instance host using OSC, or directly using an environment-specific messaging system. The method to be used is determined by the value of the module's 'direct' flag. If messages pass through the Instance host, it means that various operations can be performed on the data as it passes through. This includes:

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 send data to these modules in an efficient way, the Integra instance host needs a way to communicate directly with the environment. This is done using a target-specific bridge, which is a dynamically loaded binary shared object hosted 'inside' the instance host. 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 the 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 plug's software-specific communication mechanism that determines the protocol used to construct module implementations. It is possible, although not necessarily desirable to have several bridgess 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 PD Faust modules.

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 not part of libIntegra, it is any software that hosts Integra modules. 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 from the individual modules. 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 typical configuration 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.

libIntegra package

In addition to providing the instance host and serialization components, which constitute the bulk of the libIntegra binary shared object, the libIntegra package also provides a number of other useful tools. These include a CLI (command line interface) through which all operations can be performed in a non-GUI mode, a number of example bridge implementations, and a number of example module host implementations.

next up previous contents index
Next: Use case scenario Up: libIntegra: a system for Previous: Database   Contents   Index
Jamie Bullock, Henrik Frisk