Main program

# Overview

The main program is the part of executable that is located outside the plug-in framework. The main program is responsible for setting up the plug-in framework and for loading the desired set of plug-ins. The main program should preferably be very thin, a mere plug-in loader, because it can not fully participate in plug-in interaction. C-Pluff distribution provides a plug-in loader, cpluff-loader, which can be used as a generic main program for arbitrary plug-in collections.

# Responsibilities

The main program has several responsibilities:

- initializing the plug-in framework
- creating a plug-in context
- loading plug-ins
- controlling plug-in execution
- changing plug-in configuration (opt.)
- destroying the plug-in framework

## Initializing the plug-in framework

Plug-in framework, or the C-Pluff library, must be initialized before its services can be used. Initialization is not a thread-safe operation and should generally be done by the main program before any additional plug-in framework accessing threads are started. Initialization is done by calling cp_init. Additionally, the main program can use cp_set_fatal_error_handler to register a function that is called when a fatal error occurs. A fatal error is one that prevents the framework from continuing operation. For example, errors in operating system locking operations and a NULL pointer being passed as an argument which is expected to have a non-NULL value are fatal erors.

Here is an example of possible initialization code.

#include <locale.h>
#include <cpluff.h>
void handle_fatal_error(const char *msg) {
// ... log error, flush logs, send bug report, etc. ...
fprintf(stderr, "A fatal error occurred: %s\n", msg);
abort();
}
void initialize(void) {
cp_status_t status;
setlocale(LC_ALL, "");
cp_set_fatal_error_handler(handle_fatal_error);
status = cp_init();
if (status != CP_OK) {
// ... handle initialization failure ...
}
}
cpluff.h
C-Pluff C API header file.
cp_init
CP_IMPORT cp_status_t cp_init(void)
Initializes the plug-in framework.
cp_set_fatal_error_handler
CP_IMPORT void cp_set_fatal_error_handler(cp_fatal_error_func_t error_handler)
Sets the fatal error handler called on non-recoverable errors.
cp_status_t
cp_status_t
An enumeration of status codes returned by API functions.
Definition cpluff.h:133
CP_OK
@ CP_OK
Operation was performed successfully (equals to zero).
Definition cpluff.h:139

## Creating a plug-in context

A plug-in context represents the co-operation environment of a set of plug-ins from the perspective of a particular participating plug-in or the perspective of the main program. From main program perspective, a plug-in context is a container for a set of plug-ins. A plug-in can interact with other plug-ins in the same container.

An extensible application can have more than one plug-in container but usually one container should suffice. Due to the nature of C programs, plug-ins deployed to different containers are not very well insulated from each other. For example, global variables provided by a plug-in in one container are visible to all plug-ins in all containers. Also, by placing all plug-ins in the same container they can more efficiently share common base components which themselves might provide extensibility.

A main program creates a plug-in context, to be used as a container for plugins, using cp_create_context.

#include <cpluff.h>
cp_context_t *ctx;
void create_context(void) {
cp_status_t status;
ctx = cp_create_context(&status);
if (ctx == NULL) {
// ... handle initialization failure ...
}
}
cp_create_context
CP_IMPORT cp_context_t * cp_create_context(cp_status_t *status)
Creates a new plug-in context which can be used as a container for plug-ins.
cp_context_t
struct cp_context_t cp_context_t
A plug-in context represents the co-operation environment of a set of plug-ins from the perspective o...
Definition cpluff.h:281

## Loading plug-ins

An extensible application is made of plug-ins that can be added and removed dynamically. The plug-ins are loaded by the main program using the services provided by the framework. The framework provides couple of alternative ways of loading plug-ins.

As a lowest level operation, the main program can load individual plug-ins from known locations using cp_load_plugin_descriptor and cp_install_plugin. Here is example code that loads a set of plug-ins from file system locations listed in a file.

#include <stdio.h>
#include <cpluff.h>
extern cp_context_t *ctx;
static const char pluginListFile[] = "/etc/example/plugins.list";
void load_plugins(void) {
char plugindir[128];
FILE *lf;
// Open plug-in list file
lf = fopen(pluginListFile, "r");
if (lf == NULL) {
// ... handle loading failure ...
}
// Load each listed plug-in
while (fgets(plugindir, 128, lf) != NULL) {
cp_plugin_info_t *plugininfo;
cp_status_t status;
int i;
// Remove possible trailing newline from plug-in location
for (i = 0; plugindir[i + 1] != '\0'; i++);
if (plugindir[i] == '\n') {
plugindir[i] = '\0';
}
// Load plug-in descriptor
plugininfo = cp_load_plugin_descriptor(ctx, plugindir, &status);
if (pinfo == NULL) {
// ... handle loading failure ...
}
// Install plug-in descriptor
status = cp_install_plugin(ctx, plugininfo);
if (status != CP_OK) {
// ... handle loading failure ...
}
// Release plug-in descriptor information
cp_release_info(ctx, plugininfo);
}
// Close plug-in list file
fclose(lf);
}
cp_load_plugin_descriptor
CP_IMPORT cp_plugin_info_t * cp_load_plugin_descriptor(cp_context_t *ctx, const char *path, cp_status_t *status)
Loads a plug-in descriptor from the specified plug-in installation path and returns information about...
cp_release_info
CP_IMPORT void cp_release_info(cp_context_t *ctx, void *info)
Releases a previously obtained reference counted information object.
cp_install_plugin
CP_IMPORT cp_status_t cp_install_plugin(cp_context_t *ctx, cp_plugin_info_t *pi)
Installs the plug-in described by the specified plug-in information structure to the specified plug-i...
cp_plugin_info_t
Plug-in information structure captures information about a plug-in.
Definition cpluff.h:399

Alternatively, the main program can register and load plug-in collections. A plug-in collection is a file system directory which includes individual plug-ins in subdirectories, one plug-in in each subdirectory. Plug-in collections can be registered with a plug-in context using cp_register_pcollection. Plug-ins of the collection can then be scanned and loaded using cp_scan_plugins. Here is example code loading plug-ins from a plug-in collection.

#include <cpluff.h>
extern cp_context_t *ctx;
static const char pluginCollectionDir[] = "/etc/example/plugins";
void load_plugins(void) {
cp_status_t status;
status = cp_register_pcollection(ctx, pluginCollectionDir);
if (status != CP_OK) {
// ... handle loading failure ...
}
status = cp_scan_plugins(ctx, 0);
if (status != CP_OK) {
// ... handle loading failure ...
// (notice that some plug-ins might have been loaded)
}
}
cp_register_pcollection
CP_IMPORT cp_status_t cp_register_pcollection(cp_context_t *ctx, const char *dir)
Registers a local plug-in collection with a plug-in context.
cp_scan_plugins
CP_IMPORT cp_status_t cp_scan_plugins(cp_context_t *ctx, int flags)
Scans for plug-ins in the registered plug-in directories, installing new plug-ins and upgrading insta...

## Controlling plug-in execution

The main program controls plug-in execution by starting and stopping plug-ins and by executing run functions registered by plug-ins. Additionally, the main program can pass startup arguments to plug-ins.

When plug-ins are installed they are not yet activated and their runtime library is not even loaded at that point. The main program typically activates plug-ins by starting a main plug-in responsible for user interface or core application logic. This plug-in then implicitly causes other plug-ins to be activated via dependencies and by dynamically resolving symbols provided by other plug-ins. Plug-ins recursively activate each other until all initially needed plug-ins have been started. Some plug-ins might be activated at a later time when their functionality is needed, for example due to user action.

If a plug-in needs to perform background operations, that is operations executed outside the invocation of plug-in provided interface functions, then it can either start a new thread or it can register a run function. A run function is a function that is typically executed as part of the main loop by the main program.

The following example code shows how a main program might initialize plug-in startup arguments using cp_set_context_args, start the core plug-in using cp_start_plugin and then execute plug-in run functions using cp_run_plugins.

#include <cpluff.h>
extern cp_context_t *ctx;
static const char corePluginId[] = "org.example.core";
void run_plugins(char *argv[]) {
cp_status_t status;
// Set plug-in startup arguments
cp_set_context_args(ctx, argv);
// Start the core plug-in, possibly activating other plug-ins as well
status = cp_start_plugin(ctx, corePluginId);
if (status != CP_OK) {
// ... handle startup failure ...
}
// Execute plug-ins until there is no more work to be done
cp_run_plugins(ctx);
}
int main(int argc, char *argv[]) {
// ... do initialization and load plug-ins ...
run_plugins(argv);
// ... do destruction ...
}
cp_start_plugin
CP_IMPORT cp_status_t cp_start_plugin(cp_context_t *ctx, const char *id)
Starts a plug-in.
cp_set_context_args
CP_IMPORT void cp_set_context_args(cp_context_t *ctx, char **argv)
Sets startup arguments for the specified plug-in context.
cp_run_plugins
CP_IMPORT void cp_run_plugins(cp_context_t *ctx)
Runs the started plug-ins as long as there is something to run.

Alternatively, if the main program has some operations it must perform as part of the main loop, the call to cp_run_plugins can be replaced by code using cp_run_plugins_step like in the following example.

void mainloop(void) {
int finished = 0;
while (!finished) {
// ... do main program specific operations ...
finished = !cp_run_plugins_step(ctx);
}
}
cp_run_plugins_step
CP_IMPORT int cp_run_plugins_step(cp_context_t *ctx)
Runs one registered run function.

## Changing plug-in configuration

C-Pluff has been designed to allow dynamic changes to the plug-in configuration, that is plug-ins being added or removed without shutting down the application or the framework. It is the responsibility of the main program to manage such changes if the application is to support dynamic configuration changes.

Adding plug-ins is straightforward because there is no need to consider dependencies of active plug-ins. For example, if one uses plug-in collections as introduced above then new plug-ins can be deployed under the plug-in collection directory while the application is running and the main program can load them incrementally by calling cp_scan_plugins again. This call might be activated by some user interface element, for example a plug-in manager component which just downloaded and installed new plug-ins as requested by the user. The flags CP_SP_STOP_ALL_ON_INSTALL and CP_SP_RESTART_ACTIVE orred together can be used to cause all active plug-ins to be restarted if they do not otherwise notice the extensions provided by new plug-ins.

Upgrading plug-ins is almost as straightforward because the C-Pluff framework manages plug-in dependencies (assuming the plug-ins have declared their dependencies properly). The new version of a plug-in can be deployed under the plug-in collection directory in a new subdirectory parallel to the old version while the application is running. The main program can then call cp_scan_plugins with CP_SP_UPGRADE and CP_SP_RESTART_ACTIVE orred together. This will stop the old version of the upgraded plug-in (implicitly stopping all plug-ins that depend on it), unload the plug-in from the framework, install the new version of the plug-in and finally restart plug-ins that were active before the operation. The old version of the plug-in can now be removed from the plug-in collection. Again, CP_SP_STOP_ALL_ON_UPGRADE can be added to restart all active plug-ins.

Deleting plug-ins must be done by first stopping and unloading the plug-in to be deleted using cp_uninstall_plugin. The the plug-in can be removed from the plug-in collection.

## Destroying the plug-in framework

The plug-in framework can be destroyed and all resources released by calling cp_destroy as many times as cp_init has been called. This is not a thread-safe operation and should generally be done by the main program just before application exits. The destroy function stops and unloads all plug-ins and destroys all plug-in contexts before destroying the core framework.

Individual plug-in contexts can be destroyed by calling cp_destroy_context. The destroy function stops and unloads all plug-ins before destroying the context itself.

Generated on Sun Mar 31 2024 17:56:45 for C-Pluff C API by 1.9.8