pluginprocess.c File Reference

Source for the pluginprocess library. More...

#include "kdbpluginprocess.h"
#include <kdberrors.h>
#include <kdbinvoke.h>
#include <kdblogger.h>
#include <kdbprivate.h>
#include <errno.h>
#include <limits.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>

Include dependency graph for pluginprocess.c:

Functions
void	elektraPluginProcessStart (Plugin *handle, ElektraPluginProcess *pp)
	Start the child process' command loop. More...
int	elektraPluginProcessSend (const ElektraPluginProcess *pp, pluginprocess_t command, KeySet *originalKeySet, Key *key)
	Call a plugin's function in a child process. More...
int	elektraPluginProcessIsParent (const ElektraPluginProcess *pp)
	Check if a given plugin process is the parent or the child process. More...
ElektraPluginProcess *	elektraPluginProcessInit (Key *errorKey)
	Initialize a plugin to be executed in its own process. More...
int	elektraPluginProcessOpen (ElektraPluginProcess *pp, Key *errorKey)
	Call a plugin's open function in a child process. More...
ElektraPluginProcessCloseResult	elektraPluginProcessClose (ElektraPluginProcess *pp, Key *errorKey)
	Cleanup a plugin process. More...
void	elektraPluginProcessSetData (ElektraPluginProcess *pp, void *data)
	Store a pointer to any plugin related data that is being executed inside an own process. More...
void *	elektraPluginProcessGetData (const ElektraPluginProcess *pp)
	Get a pointer to any plugin related data stored before. More...

Detailed Description

Source for the pluginprocess library.

Executes plugins in a separate process via fork and uses a simple communication protocol based on the dump plugin via named pipes.

The communication protocol works as follows, where Child and Parent stand for the child and the parent process: 1) Four pipes are created to handle the communication in a reliable way

• parentCommandPipe is used for a keyset containing metainformation about the communication protocol, going from Parent to Child
• parentPayloadPipe is used for transferring the actual payload that gets passed to a plugin, going from Parent to Child
• childCommandPipe is used for a keyset containing metainformation about the communication protocol, going from Child to Parent
• childPayloadPipe is used for transferring the actual payload that gets passed to a plugin, going from Child to Parent 2) The parent constructs a keyset called commandKeySet, containing:
• /pluginprocess/parent a copy of the parent key passed to the plugin interface
• /pluginprocess/parent/name the name of the parent key passed to the plugin interface
• /pluginprocess/command the command that should be executed by the child process
• /pluginprocess/payload/size the size of the payload keyset, -1 if there is no payload
• /pluginprocess/version a number indicating the version of this communication protocol 3) The parent sends over the commandKeySet over the parentCommandPipe 4) For operations requiring a keyset, the parent sends the keyset (originalKeySet) that is passed to this plugin over the parentPayloadPipe 5) Child receives the commandKeySet 6) Child receives the keyset if one exists 7) Child executes the plugin on the keyset with the originalKey 8) Child adds the result value of the plugin operation to the commandKeySet into the key /pluginprocess/result 9) Child sends the commandKeySet over the childCommandPipe 10) For operations requiring a keyset, Child sends the keyset over the childPayloadPipe 11) Parent receives the commandKeySet and interprets /pluginprocess/result 12) For operations requiring a keyset, Parent receives the keyset and copies it back to originalKeySet set 13) Parent returns the result value from the child process

Copyright

BSD License (see LICENSE.md or https://www.libelektra.org)

Function Documentation

elektraPluginProcessClose()

ElektraPluginProcessCloseResult elektraPluginProcessClose	(	ElektraPluginProcess *	pp,
		Key *	errorKey
	)

Cleanup a plugin process.

This will decrease the internal counter how often open/close has been called, closing opened pipes when the counter reaches 0. This will not delete the plugin data associated with the handle as it may contain other data out of the scope of this library, so this has to be done manually like

int elektraPluginClose (Plugin * handle, Key * errorKey)
{
        ElektraPluginProcess * pp = elektraPluginGetData (handle);
        if (pp && elektraPluginProcessIsParent (pp)) {
                ElektraPluginProcessCloseResult result = elektraPluginProcessClose (pp, errorKey);
                if (result.cleanedUp) elektraPluginSetData (handle, NULL);
                return result.result;
        }
 
        // actual plugin functionality to be executed in a child process
        return ELEKTRA_PLUGIN_STATUS_SUCCESS;
}

Note that pp might be null here if the initialization failed!

Parameters

pp	the data structure containing the plugin's process information

Return values

1	if the data structure got cleaned up
0	if the data structure is still used

elektraPluginProcessGetData()

void* elektraPluginProcessGetData

(

const ElektraPluginProcess *

pp

)

Get a pointer to any plugin related data stored before.

If elektraPluginProcessSetData was not called earlier, NULL will be returned.

Parameters

pp	the data structure containing the plugin's process information

Return values

a	pointer to the data

elektraPluginProcessInit()

ElektraPluginProcess* elektraPluginProcessInit

(

Key *

errorKey

)

Initialize a plugin to be executed in its own process.

This will prepare all the required resources and then fork the current process. After the initialization the child process will typically call the command loop while the parent starts to send commands to it. Also the resulting process information has to be stored for the plugin. In order to allow users to handle custom plugin data this will not automatically call elektraPluginSetData.

Typically called in a plugin's open function like (assuming no custom plugin data):

int elektraPluginOpen (Plugin * handle, Key * errorKey)
{
        ElektraPluginProcess * pp = elektraPluginGetData (handle);
        if (pp == NULL)
        {
                if ((pp = elektraPluginProcessInit (errorKey)) == NULL) return ELEKTRA_PLUGIN_STATUS_ERROR;
                elektraPluginSetData (handle, pp);
                if (!elektraPluginProcessIsParent (pp)) elektraPluginProcessStart (handle, pp);
        }
        if (elektraPluginProcessIsParent (pp)) return elektraPluginProcessOpen (pp, errorKey);
 
        // actual plugin functionality to be executed in a child process
        return ELEKTRA_PLUGIN_STATUS_SUCCESS;
}

Parameters

handle	the plugin's handle
errorKey	a key where error messages will be set

Return values

NULL	if the initialization failed
a	pointer to the information

elektraPluginProcessIsParent()

int elektraPluginProcessIsParent

(

const ElektraPluginProcess *

pp

)

Check if a given plugin process is the parent or the child process.

Parameters

pp	the data structure containing the plugin's process information

Return values

0	if it's the child process
the	child process' pid otherwise

elektraPluginProcessOpen()

int elektraPluginProcessOpen	(	ElektraPluginProcess *	pp,
		Key *	errorKey
	)

Call a plugin's open function in a child process.

This will increase the internal counter how often open/close has been called, so the opened pipes and forks will not be closed too early.

Parameters

pp	the data structure containing the plugin's process information
errorKey	a key where error messages will be set

Return values

the	return value of the plugin's open function

See also

elektraPluginProcessInit for an example how and where this function is typically used

elektraPluginProcessSend()

int elektraPluginProcessSend	(	const ElektraPluginProcess *	pp,
		pluginprocess_t	command,
		KeySet *	originalKeySet,
		Key *	key
	)

Call a plugin's function in a child process.

This will wrap all the required information to execute the given command in a keyset and send it over to the child process. Then it waits for the child process's answer and copies the result back into the original plugin keyset and plugin key.

Typically called like

int elektraPluginSet (Plugin * handle, KeySet * returned, Key * parentKey)
{
        ElektraPluginProcess * pp = elektraPluginGetData (handle);
        if (elektraPluginProcessIsParent (pp)) return elektraPluginProcessSend (pp, ELEKTRA_PLUGINPROCESS_SET, returned, parentKey);
 
        // actual plugin functionality to be executed in a child process
        return ELEKTRA_PLUGIN_STATUS_SUCCESS;
}

Parameters

pp	the data structure containing the plugin's process information
command	the plugin command that should be executed, e.g. ELEKTRA_PLUGINPROCESS_GET
originalKeySet	the original key set that the parent process receives
key	the original key the parent process receives

Return values

ELEKTRA_PLUGIN_STATUS_ERROR	if the child process communication failed
the	called plugin's return value otherwise

See also

elektraPluginProcessIsParent for checking if we are in the parent or child process

elektraPluginProcessSetData()

void elektraPluginProcessSetData	(	ElektraPluginProcess *	pp,
		void *	data
	)

Store a pointer to any plugin related data that is being executed inside an own process.

This is required in case additional arbitrary plugin data should be stored. Pluginprocess has to be stored using elektraPluginSetData. Plugin data for the child process has to be stored using this function like

int elektraPluginOpen (Plugin * handle, Key * errorKey)
{
        ElektraPluginProcess * pp = elektraPluginGetData (handle);
        if (pp == NULL)
        {
                if ((pp = elektraPluginProcessInit (errorKey)) == NULL) return ELEKTRA_PLUGIN_STATUS_ERROR;
                ArbitraryPluginData * data = // initialize your plugin data
                elektraPluginProcessSetData (pp, data);
                elektraPluginSetData (handle, pp);
                if (!elektraPluginProcessIsParent (pp)) elektraPluginProcessStart (handle, pp);
        }
        if (elektraPluginProcessIsParent (pp)) return elektraPluginProcessOpen (pp, errorKey);
 
        // actual plugin functionality to be executed in a child process
        return ELEKTRA_PLUGIN_STATUS_SUCCESS;
}

Furthermore ensure to cleanup the data after the plugin is done like

int elektraPluginClose (Plugin * handle, Key * errorKey)
{
        ElektraPluginProcess * pp = elektraPluginGetData (handle);
        if (elektraPluginProcessIsParent (pp)) {
                ArbitraryPluginData * data = elektraPluginProcessGetData (pp);
                ElektraPluginProcessCloseResult result = elektraPluginProcessClose (pp, errorKey);
                if (result.cleanedUp)
                {
                        elektraPluginSetData (handle, NULL);
                        // cleanup data here, this was the last call to the plugin
                }
                return result.result;
        }
 
        // actual plugin functionality to be executed in a child process
        return ELEKTRA_PLUGIN_STATUS_SUCCESS;
}

This way you can use elektraPluginProcessGetData (handle) in your child process to get the data you want your plugin to work with.

Parameters

pp	the data structure containing the plugin's process information
data	the pointer to the data

elektraPluginProcessStart()

void elektraPluginProcessStart	(	Plugin *	handle,
		ElektraPluginProcess *	pp
	)

Start the child process' command loop.

This will make the child process wait for plugin commands and execute them, returning the result to the parent. This is typically called in a plugin's open function.

Parameters

handle	the plugin's handle
pp	the data structure containing the plugin's process information

See also

elektraPluginProcessInit how to use this function in a Plugins