1.5.1
Started plug-ins can use cp_run_function to register a run function which is called when the main program calls cp_run_plugins or cp_run_plugins_step. A run function should do a finite chunk of work and then return telling whether there is more work to be done. A run function is automatically unregistered when the plug-in is stopped. Run functions make it possible for plug-ins to control the flow of execution or they can be used as a coarse way of task switching if there is no multi-threading support.
The C-Pluff distribution includes a generic main program, cpluff-loader, which only acts as a plug-in loader. It loads and starts up the specified plug-ins, passing any additional startup arguments to them and then just calls run functions of the plug-ins. This makes it is possible to put all the application specific logic in plug-ins. Application does not necessarily need a main program of its own.
It is also safe, from framework perspective, to call these functions from multiple threads. Run functions may then be executed in parallel threads.
Functions | |
| cp_status_t | cp_run_function (cp_context_t *ctx, cp_run_func_t runfunc) |
| Registers a new run function. | |
| void | cp_run_plugins (cp_context_t *ctx) |
| Runs the started plug-ins as long as there is something to run. | |
| int | cp_run_plugins_step (cp_context_t *ctx) |
| Runs one registered run function. | |
| void | cp_set_context_args (cp_context_t *ctx, char **argv) |
| Sets startup arguments for the specified plug-in context. | |
| char ** | cp_get_context_args (cp_context_t *ctx, int *argc) |
| Returns the startup arguments associated with the specified plug-in context. | |
| cp_status_t cp_run_function | ( | cp_context_t * | ctx, | |
| cp_run_func_t | runfunc | |||
| ) |
Registers a new run function.
The plug-in instance data pointer is given to the run function as a parameter. The run function must return zero if it has finished its work or non-zero if it should be called again later. The run function is unregistered when it returns zero. Plug-in framework functions stopping the registering plug-in must not be called from within a run function. This function does nothing if the specified run function is already registered for the calling plug-in instance.
| ctx | the plug-in context of the registering plug-in | |
| runfunc | the run function to be registered |
| void cp_run_plugins | ( | cp_context_t * | ctx | ) |
Runs the started plug-ins as long as there is something to run.
This function calls repeatedly run functions registered by started plug-ins until there are no more active run functions. This function is normally called by a thin main proram, a loader, which loads plug-ins, starts some plug-ins and then passes control over to the started plug-ins.
| ctx | the plug-in context containing the plug-ins |
| int cp_run_plugins_step | ( | cp_context_t * | ctx | ) |
Runs one registered run function.
This function calls one active run function registered by a started plug-in. When the run function returns this function also returns and passes control back to the main program. The return value can be used to determine whether there are any active run functions left. This function does nothing if there are no active registered run functions.
| ctx | the plug-in context containing the plug-ins |
| void cp_set_context_args | ( | cp_context_t * | ctx, | |
| char ** | argv | |||
| ) |
Sets startup arguments for the specified plug-in context.
Like for usual C main functions, the first argument is expected to be the name of the program being executed or an empty string and the argument array should be terminated by NULL entry. If the main program is about to pass startup arguments to plug-ins it should call this function before starting any plug-ins in the context. The arguments are not copied and the caller is responsible for keeping the argument data available once the arguments have been set until the context is destroyed. Plug-ins can access the startup arguments using cp_get_context_args.
| ctx | the plug-in context | |
| argv | a NULL-terminated array of arguments |
| char** cp_get_context_args | ( | cp_context_t * | ctx, | |
| int * | argc | |||
| ) |
Returns the startup arguments associated with the specified plug-in context.
This function is intended to be used by a plug-in runtime. Startup arguments are set by the main program using cp_set_context_args. The returned argument count is zero and the array pointer is NULL if no arguments have been set.
| ctx | the plug-in context | |
| argc | a pointer to a location where the number of startup arguments is stored, or NULL for none |
Generated on Fri Apr 6 15:40:55 2007 for C-Pluff C API by 1.5.1