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 <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
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.
- Copyright
- BSD License (see LICENSE.md or https://www.libelektra.org)
int 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
1 int elektraPluginClose (Plugin * handle, Key * errorKey)
3 ElektraPluginProcess * pp = elektraPluginGetData (handle);
4 if (elektraPluginProcessIsParent (pp)) {
5 int result = elektraPluginProcessSend (pp, ELEKTRA_PLUGIN_CLOSE, NULL, errorKey);
6 if (elektraPluginProcessClose (pp, errorKey)) elektraPluginSetData (handle, NULL);
10 // actual plugin functionality to be executed in a child process
11 return ELEKTRA_PLUGIN_STATUS_SUCCESS;
- 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 |
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):
1 int elektraPluginOpen (Plugin * handle, Key * errorKey)
3 ElektraPluginProcess * pp = elektraPluginGetData (handle);
6 if ((pp = elektraPluginProcessInit (handle, errorKey)) == NULL) return ELEKTRA_PLUGIN_STATUS_ERROR;
7 elektraPluginSetData (handle, pp);
8 if (!elektraPluginProcessIsParent (pp)) elektraPluginProcessStart (handle, pp);
10 if (elektraPluginProcessIsParent (pp)) return elektraPluginProcessOpen (pp, errorKey);
12 // actual plugin functionality to be executed in a child process
13 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 |
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 |
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
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
1 int elektraPluginSet (Plugin * handle, KeySet * returned, Key * parentKey)
3 ElektraPluginProcess * pp = elektraPluginGetData (handle);
4 if (elektraPluginProcessIsParent (pp)) return elektraPluginProcessSend (pp, ELEKTRA_PLUGIN_SET, returned, parentKey);
6 // actual plugin functionality to be executed in a child process
7 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_PLUGIN_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
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