C-Pluff C API  0.2.0
Plug-in execution

These functions support a plug-in controlled execution model. More...


CP_IMPORT cp_status_t cp_run_function (cp_context_t *ctx, cp_run_func_t runfunc)
 Registers a new run function. More...
CP_IMPORT void cp_run_plugins (cp_context_t *ctx)
 Runs the started plug-ins as long as there is something to run. More...
CP_IMPORT int cp_run_plugins_step (cp_context_t *ctx)
 Runs one registered run function. More...
CP_IMPORT void cp_set_context_args (cp_context_t *ctx, char **argv)
 Sets startup arguments for the specified plug-in context. More...
CP_IMPORT char ** cp_get_context_args (cp_context_t *ctx, int *argc)
 Returns the startup arguments associated with the specified plug-in context. More...

Detailed Description

These functions support a plug-in controlled execution model.

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.

Function Documentation

◆ cp_run_function()

CP_IMPORT 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.

ctxthe plug-in context of the registering plug-in
runfuncthe run function to be registered
CP_OK (zero) on success or an error code on failure

◆ 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.

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.

ctxthe plug-in context containing the plug-ins

◆ cp_run_plugins_step()

CP_IMPORT 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.

ctxthe plug-in context containing the plug-ins
whether there are active run functions waiting to be run

◆ 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.

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.

ctxthe plug-in context
argva NULL-terminated array of arguments

◆ cp_get_context_args()

CP_IMPORT 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.

ctxthe plug-in context
argca pointer to a location where the number of startup arguments is stored, or NULL for none
an argument array terminated by NULL or NULL if not set

Generated on Fri May 1 2020 01:06:58 for C-Pluff C API by doxygen 1.8.13