1 /*-------------------------------------------------------------------------
2 * C-Pluff, a plug-in framework for C
3 * Copyright 2007 Johannes Lehtinen
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included
13 * in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 *-----------------------------------------------------------------------*/
25 * @page cMainProgram Main program
27 * @section cMainProgramOverview Overview
29 * The main program is the part of executable that is located outside the
30 * plug-in framework. The main program is responsible for setting up
31 * the plug-in framework and for loading the desired set of
32 * @ref plugin "plug-ins". The main program should preferably be very
33 * thin, a mere plug-in loader, because it can not fully participate in plug-in
34 * interaction. C-Pluff distribution provides a plug-in loader,
35 * @ref cpluff-loader, which can be used as a generic main program for
36 * arbitrary plug-in collections.
38 * @section cMainProgramResponsibilities Responsibilities
40 * The main program has several responsibilities:
42 * - @ref cMainProgramInitFramework "initializing the plug-in framework"
43 * - @ref cMainProgramCreateContext "creating a plug-in context"
44 * - @ref cMainProgramLoad "loading plug-ins"
45 * - @ref cMainProgramExec "controlling plug-in execution"
46 * - @ref cMainProgramChange "changing plug-in configuration" (opt.)
47 * - @ref cMainProgramDestroyFramework "destroying the plug-in framework"
49 * @subsection cMainProgramInitFramework Initializing the plug-in framework
51 * Plug-in framework, or the C-Pluff library, must be initialized before its
52 * services can be used.
53 * Initialization is not a thread-safe operation and should generally be
54 * done by the main program before any additional plug-in framework accessing
55 * threads are started. Initialization is done by calling ::cp_init.
56 * Additionally, the main program can use ::cp_set_fatal_error_handler to register
57 * a function that is called when a fatal error occurs. A fatal error is one
58 * that prevents the framework from continuing operation. For example,
59 * errors in operating system locking operations and a NULL pointer being
60 * passed as an argument which is expected to have a non-NULL value are fatal
63 * Here is an example of possible initialization code.
69 * void handle_fatal_error(const char *msg) {
71 * // ... log error, flush logs, send bug report, etc. ...
73 * fprintf(stderr, "A fatal error occurred: %s\n", msg);
77 * void initialize(void) {
80 * setlocale(LC_ALL, "");
81 * cp_set_fatal_error_handler(handle_fatal_error);
83 * if (status != CP_OK) {
84 * // ... handle initialization failure ...
89 * @subsection cMainProgramCreateContext Creating a plug-in context
91 * A plug-in context represents the co-operation environment of a set of
92 * plug-ins from the perspective of a particular participating plug-in or
93 * the perspective of the main program. From main program perspective, a
94 * plug-in context is a container for a set of plug-ins. A plug-in can interact
95 * with other plug-ins in the same container.
97 * An extensible application can have more than one plug-in container but
98 * usually one container should suffice. Due to the nature of C programs,
99 * plug-ins deployed to different containers are not very well insulated from
100 * each other. For example, global variables provided by a plug-in in one
101 * container are visible to all plug-ins in all containers. Also, by placing
102 * all plug-ins in the same container they can more efficiently share common
103 * base components which themselves might provide extensibility.
105 * A main program creates a plug-in context, to be used as a container for
106 * plugins, using ::cp_create_context.
109 * #include <cpluff.h>
113 * void create_context(void) {
114 * cp_status_t status;
116 * ctx = cp_create_context(&status);
118 * // ... handle initialization failure ...
123 * @subsection cMainProgramLoad Loading plug-ins
125 * An extensible application is made of plug-ins that can be added and removed
126 * dynamically. The plug-ins are loaded by the main program using the services
127 * provided by the framework. The framework provides couple of alternative
128 * ways of loading plug-ins.
130 * As a lowest level operation, the main program can
131 * load individual plug-ins from known locations using
132 * ::cp_load_plugin_descriptor and ::cp_install_plugin. Here is example code
133 * that loads a set of plug-ins from file system locations listed in a file.
137 * #include <cpluff.h>
139 * extern cp_context_t *ctx;
140 * static const char pluginListFile[] = "/etc/example/plugins.list";
142 * void load_plugins(void) {
143 * char plugindir[128];
146 * // Open plug-in list file
147 * lf = fopen(pluginListFile, "r");
149 * // ... handle loading failure ...
152 * // Load each listed plug-in
153 * while (fgets(plugindir, 128, lf) != NULL) {
154 * cp_plugin_info_t *plugininfo;
155 * cp_status_t status;
158 * // Remove possible trailing newline from plug-in location
159 * for (i = 0; plugindir[i + 1] != '\0'; i++);
160 * if (plugindir[i] == '\n') {
161 * plugindir[i] = '\0';
164 * // Load plug-in descriptor
165 * plugininfo = cp_load_plugin_descriptor(ctx, plugindir, &status);
166 * if (pinfo == NULL) {
167 * // ... handle loading failure ...
170 * // Install plug-in descriptor
171 * status = cp_install_plugin(ctx, plugininfo);
172 * if (status != CP_OK) {
173 * // ... handle loading failure ...
176 * // Release plug-in descriptor information
177 * cp_release_info(ctx, plugininfo);
180 * // Close plug-in list file
185 * Alternatively, the main program can register and load plug-in collections.
186 * A plug-in collection is a file system directory which includes individual
187 * plug-ins in subdirectories, one plug-in in each subdirectory. Plug-in
188 * collections can be registered with a plug-in context using
189 * ::cp_register_pcollection. Plug-ins of the collection can then be scanned
190 * and loaded using ::cp_scan_plugins. Here is example code loading plug-ins
191 * from a plug-in collection.
194 * #include <cpluff.h>
196 * extern cp_context_t *ctx;
197 * static const char pluginCollectionDir[] = "/etc/example/plugins";
199 * void load_plugins(void) {
200 * cp_status_t status;
202 * status = cp_register_pcollection(ctx, pluginCollectionDir);
203 * if (status != CP_OK) {
204 * // ... handle loading failure ...
206 * status = cp_scan_plugins(ctx, 0);
207 * if (status != CP_OK) {
208 * // ... handle loading failure ...
209 * // (notice that some plug-ins might have been loaded)
214 * @subsection cMainProgramExec Controlling plug-in execution
216 * The main program controls plug-in execution by starting and stopping
217 * plug-ins and by executing run functions registered by plug-ins.
218 * Additionally, the main program can pass startup arguments to plug-ins.
220 * When plug-ins are installed they are not yet activated and their
221 * runtime library is not even loaded at that point. The main program
222 * typically activates plug-ins by starting a main plug-in
223 * responsible for user interface or core application logic. This plug-in
224 * then implicitly causes other plug-ins to be activated via dependencies and
225 * by dynamically resolving symbols provided by other plug-ins. Plug-ins
226 * recursively activate each other until all initially needed plug-ins have
227 * been started. Some plug-ins might be activated at a later time when their
228 * functionality is needed, for example due to user action.
230 * If a plug-in needs to perform background operations, that is operations
231 * executed outside the invocation of plug-in provided interface functions,
232 * then it can either start a new thread or it can register a run function.
233 * A run function is a function that is typically executed as part of the
234 * main loop by the main program.
236 * The following example code shows how a main program might initialize
237 * plug-in startup arguments using ::cp_set_context_args, start the core
238 * plug-in using ::cp_start_plugin and then execute plug-in run functions
239 * using ::cp_run_plugins.
242 * #include <cpluff.h>
244 * extern cp_context_t *ctx;
245 * static const char corePluginId[] = "org.example.core";
247 * void run_plugins(char *argv[]) {
248 * cp_status_t status;
250 * // Set plug-in startup arguments
251 * cp_set_context_args(ctx, argv);
253 * // Start the core plug-in, possibly activating other plug-ins as well
254 * status = cp_start_plugin(ctx, corePluginId);
255 * if (status != CP_OK) {
256 * // ... handle startup failure ...
259 * // Execute plug-ins until there is no more work to be done
260 * cp_run_plugins(ctx);
263 * int main(int argc, char *argv[]) {
264 * // ... do initialization and load plug-ins ...
268 * // ... do destruction ...
272 * Alternatively, if the main program has some operations it must perform
273 * as part of the main loop, the call to ::cp_run_plugins can be replaced
274 * by code using ::cp_run_plugins_step like in the following example.
277 * void mainloop(void) {
280 * while (!finished) {
281 * // ... do main program specific operations ...
283 * finished = !cp_run_plugins_step(ctx);
288 * @subsection cMainProgramChange Changing plug-in configuration
290 * C-Pluff has been designed to allow dynamic changes to the plug-in
291 * configuration, that is plug-ins being added or removed without shutting
292 * down the application or the framework. It is the responsibility of the
293 * main program to manage such changes if the application is to support
294 * dynamic configuration changes.
296 * Adding plug-ins is straightforward because there is no need to
297 * consider dependencies of active plug-ins. For example, if one uses
298 * plug-in collections as introduced above then new plug-ins can be
299 * deployed under the plug-in collection directory while the application is
300 * running and the main program can load them incrementally by calling
301 * ::cp_scan_plugins again. This call might be activated by some user interface
302 * element, for example a plug-in manager component which just downloaded and
303 * installed new plug-ins as requested by the user. The flags
304 * #CP_SP_STOP_ALL_ON_INSTALL and #CP_SP_RESTART_ACTIVE
305 * orred together can be used to cause all active plug-ins to be restarted
306 * if they do not otherwise notice the extensions provided by new plug-ins.
308 * Upgrading plug-ins is almost as straightforward because the C-Pluff
309 * framework manages plug-in dependencies (assuming the plug-ins have
310 * declared their dependencies properly). The new version of a plug-in
311 * can be deployed under the plug-in collection directory in a
312 * new subdirectory parallel to the old version while the application is
313 * running. The main program can then call ::cp_scan_plugins with
314 * #CP_SP_UPGRADE and #CP_SP_RESTART_ACTIVE orred together. This will stop
315 * the old version of the upgraded plug-in (implicitly stopping all plug-ins
316 * that depend on it), unload the plug-in from the framework, install the
317 * new version of the plug-in and finally restart plug-ins that were
318 * active before the operation. The old version of the plug-in can now
319 * be removed from the plug-in collection. Again, #CP_SP_STOP_ALL_ON_UPGRADE
320 * can be added to restart all active plug-ins.
322 * Deleting plug-ins must be done by first stopping and unloading the
323 * plug-in to be deleted using ::cp_uninstall_plugin. The the plug-in can
324 * be removed from the plug-in collection.
326 * @subsection cMainProgramDestroyFramework Destroying the plug-in framework
328 * The plug-in framework can be destroyed and all resources released by
329 * calling ::cp_destroy as many times as ::cp_init has been called. This
330 * is not a thread-safe operation and should generally be done by the main
331 * program just before application exits. The destroy function
332 * stops and unloads all plug-ins and destroys all plug-in contexts before
333 * destroying the core framework.
335 * Individual plug-in contexts can be destroyed by calling
336 * ::cp_destroy_context. The destroy function stops and unloads all plug-ins
337 * before destroying the context itself.