diff options
Diffstat (limited to 'lib/cpluff/libcpluff/docsrc/mainprog.dox')
| -rw-r--r-- | lib/cpluff/libcpluff/docsrc/mainprog.dox | 338 |
1 files changed, 0 insertions, 338 deletions
diff --git a/lib/cpluff/libcpluff/docsrc/mainprog.dox b/lib/cpluff/libcpluff/docsrc/mainprog.dox deleted file mode 100644 index 78407d032e..0000000000 --- a/lib/cpluff/libcpluff/docsrc/mainprog.dox +++ /dev/null @@ -1,338 +0,0 @@ -/*------------------------------------------------------------------------- - * C-Pluff, a plug-in framework for C - * Copyright 2007 Johannes Lehtinen - * - * Permission is hereby granted, free of charge, to any person obtaining a - * copy of this software and associated documentation files (the "Software"), - * to deal in the Software without restriction, including without limitation - * the rights to use, copy, modify, merge, publish, distribute, sublicense, - * and/or sell copies of the Software, and to permit persons to whom the - * Software is furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included - * in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS - * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, - * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE - * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - *-----------------------------------------------------------------------*/ - -/** - * @page cMainProgram Main program - * - * @section cMainProgramOverview 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 - * @ref plugin "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, - * @ref cpluff-loader, which can be used as a generic main program for - * arbitrary plug-in collections. - * - * @section cMainProgramResponsibilities Responsibilities - * - * The main program has several responsibilities: - * - * - @ref cMainProgramInitFramework "initializing the plug-in framework" - * - @ref cMainProgramCreateContext "creating a plug-in context" - * - @ref cMainProgramLoad "loading plug-ins" - * - @ref cMainProgramExec "controlling plug-in execution" - * - @ref cMainProgramChange "changing plug-in configuration" (opt.) - * - @ref cMainProgramDestroyFramework "destroying the plug-in framework" - * - * @subsection cMainProgramInitFramework 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. - * - * @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 ... - * } - * } - * @endcode - * - * @subsection cMainProgramCreateContext 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. - * - * @code - * #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 ... - * } - * } - * @endcode - * - * @subsection cMainProgramLoad 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. - * - * @code - * #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); - * } - * @endcode - * - * 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. - * - * @code - * #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) - * } - * } - * @endcode - * - * @subsection cMainProgramExec 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. - * - * @code - * #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 ... - * } - * @endcode - * - * 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. - * - * @code - * void mainloop(void) { - * int finished = 0; - * - * while (!finished) { - * // ... do main program specific operations ... - * - * finished = !cp_run_plugins_step(ctx); - * } - * } - * @endcode - * - * @subsection cMainProgramChange 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. - * - * @subsection cMainProgramDestroyFramework 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. - */ |