Pipeline API

Data Structures
struct	_pipeline
	Pipeline execution functions. More...
struct	pipeline_eventnames_t
	Names of the event handlers within the pipeline. More...
struct	pipeline_interface_t
	Interface returned to other modules which require integration with the pipeline. More...

Enumerations

Variables
int(*	pipeline_interface_t::pipeline_database_delete )(const char *symbol)
	Delete all data for a symbol. More...
int(*	pipeline_interface_t::pipeline_database_insert )(const char *symbol, const char *key, pipeline_datatype_t type, void *dataptr)
	Insert new data into the database. More...
int(*	pipeline_interface_t::pipeline_database_retrieve )(const char *symbol, const char *key, pipeline_datatype_t *type, void **dataptr)
	Retrieve some data from the database. More...
pipeline_t *(*	pipeline_interface_t::pipeline_generate )(char *file, pipeline_eventnames_t *eventnames)
	Generate the pipeline. More...
pipeline_t *(*	pipeline_interface_t::pipeline_generate_with_log )(char *file, ds_log_t *logfile, pipeline_eventnames_t *eventnames)
	Generate the pipeline. More...
void *(*	pipeline_interface_t::pipeline_get_closure )(void *state)
	Gets the closure associated with the current function. More...
int(*	pipeline_interface_t::pipeline_get_num_args )(void *state)
	Get number of arguments passed to a pipeline function. More...
int(*	pipeline_interface_t::pipeline_getarg )(void *state, int argnum, pipeline_datatype_t type, void *dest)
	Get an argument for a function. More...
int(*	pipeline_interface_t::pipeline_getarg_from_map )(void *state, int argnum, const char *key, pipeline_datatype_t type, void *dest)
	Get a value for a key within a map parameter for a function. More...
int(*	pipeline_interface_t::pipeline_getarg_map_keys )(void *state, int argnum, char ***dest)
	Get a list of keys within the map at the specified argument. More...
int(*	pipeline_interface_t::pipeline_initialise )(pipeline_t *pipe)
	Initialise the pipeline. More...
int(*	pipeline_interface_t::pipeline_register_function )(char *name, pipeline_cb callback)
	Make a function available to a pipeline. More...
int(*	pipeline_interface_t::pipeline_register_function_closure )(char *name, pipeline_cb callback, void *closure)
	Make a function available to a pipeline (with a closure) More...
int(*	pipeline_interface_t::pipeline_release )(pipeline_t *pipeline)
	Release a pipeline. More...
pipeline_return_type_t(*	pipeline_interface_t::pipeline_return )(void *state)
	Function to return the appropriate value to the script. More...
int(*	pipeline_interface_t::pipeline_setret )(void *state, pipeline_datatype_t type, void *retval)
	Set a return value for a function. More...
int(*	pipeline_interface_t::pipeline_setret_array )(void *state, int num, char **array)
	Set an array as the return value for a pipeline function. More...
int(*	pipeline_interface_t::pipeline_setret_map )(void *state, int num, char **map_values)
	Set a map as the return value for a pipeline function. More...

Detailed Description

The Transformer provides a means to allow C modules to expose C methods to the pipeline. An example is shown below.

#include "transformer.h"
#include "pipeline.h"


static pipeline_interface_t  *pipeline_interface = NULL;
static int example_register_pipeline_cb(int id, int val, void *data);

void mod_init(char *name)
{
    /* Standard module code */



    /*  Timed event to register pipeline functions since the pipeline module may be loaded after example */
    ds_add_timed_event(0, 0.1, example_register_pipeline_cb, 0, NULL);
}

static NATIVE_FUNC(example_add, state)
{
    char       num1;
    int        num2;
    int        ret = -1;

    /* Retrieve the 1st argument from the pipeline context */
    if (pipeline_interface->pipeline_getarg(state, 1, PIPELINE_INTEGER, &num1) != 0) {
        printf("called with no arguments\n");
        pipeline_interface->pipeline_setret(state, PIPELINE_INTEGER, &ret);
        return pipeline_interface->pipeline_return(state);
    }

    /* Retrieve the 2nd argument from the pipeline context */
    if (pipeline_interface->pipeline_getarg(state, 1, PIPELINE_INTEGER, &num2) != 0) {
        printf("called with 1 argument, 2 required\n");
        pipeline_interface->pipeline_setret(state, PIPELINE_INTEGER, &ret);
        return pipeline_interface->pipeline_return(state);
    }
    ret = num1 + num2;

    pipeline_interface->pipeline_setret(state, PIPELINE_INTEGER, &ret);

    /* Return the result to the pipeline context */
    return pipeline_interface->pipeline_return(state);
}

static const pipeline_module_func_t example_methods[] = {
    { "add",   "add",    example_add },
    { NULL, NULL }
};

static int example_register_pipeline_cb(int id, int val, void *data)
{
    pipeline_interface_t   *(*get_pipeline)();

    /* Get the pipeline */
    if ( ( get_pipeline = tf_find_function("pipeline_get_interface") ) != NULL ) {
        pipeline_interface = get_pipeline();
        if ( pipeline_interface != NULL ) {
            /* Register the function as a global function */
            pipeline_interface->pipeline_register_function("example_add", example_add);

            /* Register the methods under a package named "example" */
            pipeline_interface->pipeline_register_library("example", &example_methods[0], NULL);
        }
    }

    return 0;
}

To call this function from a Lua module do this

local num1 = 1
local num2 = 2
local num3 = example.add(num1, num2)

or

local num3 = example_add(num1, num2)

Enumeration Type Documentation

enum pipeline_datatype_t

Argument types.

See also

pipeline_getarg()

pipeline_setret()

Enumerator
PIPELINE_INTEGER	An integer argument
PIPELINE_STRING	A string argument
PIPELINE_FLOAT	A floating point argument
PIPELINE_DSDATA	A dsdata argument
PIPELINE_COUNTER	An integer value protected by a semaphore
PIPELINE_NULL	Null return value (for return values)

Variable Documentation

int(* pipeline_interface_t::pipeline_database_delete) (const char *symbol)

Delete all data for a symbol.

Parameters

symbol

- Symbol to delete data for

Return values

0	- Success
-1	- Failure

int(* pipeline_interface_t::pipeline_database_insert) (const char *symbol, const char *key, pipeline_datatype_t type, void *dataptr)

Insert new data into the database.

Parameters

symbol	- Symbol name that we want to insert under
key	- Key for insertion
type	- Type of data to insert
dataptr	- Pointer to data

Return values

0

- Success

int(* pipeline_interface_t::pipeline_database_retrieve) (const char *symbol, const char *key, pipeline_datatype_t *type, void **dataptr)

Retrieve some data from the database.

Parameters

	symbol	- Symbol to retrieve data for
	key	- Key to retrieve
[out]	type	- Destination datatype
[out]	dataptr	- Destination dataptr

Return values

0	- Key found
-1	- Key not found

Note

Unsafe should a pipeline alter the database contents

pipeline_t*(* pipeline_interface_t::pipeline_generate) (char *file, pipeline_eventnames_t *eventnames)

Generate the pipeline.

Parameters

file	- File that the function is located in
events	- Functions to call on receipt of an event

Returns

A pipeline_t on success

Return values

NULL	- Processing of the pipeline wasn't successful

pipeline_t*(* pipeline_interface_t::pipeline_generate_with_log) (char *file, ds_log_t *logfile, pipeline_eventnames_t *eventnames)

Generate the pipeline.

Parameters

file	- File that the function is located in
logfile	- Logfile to output log messages to
events	- Functions to call on receipt of an event

Returns

A pipeline_t on success

Return values

NULL	- Processing of the pipeline wasn't successful

void*(* pipeline_interface_t::pipeline_get_closure) (void *state)

Gets the closure associated with the current function.

Returns

The closure

int(* pipeline_interface_t::pipeline_get_num_args) (void *state)

Get number of arguments passed to a pipeline function.

Parameters

state

- Script state

Returns

number of arguments on the lua stack

int(* pipeline_interface_t::pipeline_getarg) (void *state, int argnum, pipeline_datatype_t type, void *dest)

Get an argument for a function.

Parameters

state	- Script state
argnum	- Argument number
type	- Datatype that we want
dest	- Pointer to place the argument at

Return values

0	- Success
-1	- Failure

Note

Returned values should not be free()'d. They will be released on return from the function

int(* pipeline_interface_t::pipeline_getarg_from_map) (void *state, int argnum, const char *key, pipeline_datatype_t type, void *dest)

Get a value for a key within a map parameter for a function.

Parameters

state	- Script state
argnum	- Argument number
key	- Key of the map
type	- Datatype that we want
dest	- Pointer to place the argument at

Return values

0	- Success
-1	- Failure

Note

Returned values should not be free()'d. They will be released on return from the function

int(* pipeline_interface_t::pipeline_getarg_map_keys) (void *state, int argnum, char ***dest)

Get a list of keys within the map at the specified argument.

Parameters

state	- Script state
argnum	- Argument number
dest	- Pointer to place the argument at

Return values

-1

- Failure

Returns

- Number of keys

Note

The returned array should be free()'d but the keys should not be.

int(* pipeline_interface_t::pipeline_initialise) (pipeline_t *pipe)

Initialise the pipeline.

Parameters

pipe	- Pipeline to initialise

Return values

0	- Success
-1	- Failure

This function calls the defined "initialise" function

int(* pipeline_interface_t::pipeline_register_function) (char *name, pipeline_cb callback)

Make a function available to a pipeline.

Parameters

name	- Name of the function
func	- Callback for this function

Return values

0	- Success
-1	- Failure

A function is available to all pipelines constructed after the registration

int(* pipeline_interface_t::pipeline_register_function_closure) (char *name, pipeline_cb callback, void *closure)

Make a function available to a pipeline (with a closure)

Parameters

name	- Name of the function
func	- Callback for this function
closure	- Closure to associate with the function

Return values

0	- Success
-1	- Failure

A function is available to all pipelines constructed after the registration

int(* pipeline_interface_t::pipeline_release) (pipeline_t *pipeline)

Release a pipeline.

Parameters

pipe	- Pipeline to release

Return values

0	- Success
-1	- Failure

pipeline_return_type_t(* pipeline_interface_t::pipeline_return) (void *state)

Function to return the appropriate value to the script.

Parameters

state

- script state

int(* pipeline_interface_t::pipeline_setret) (void *state, pipeline_datatype_t type, void *retval)

Set a return value for a function.

Parameters

state	- Script state
type	- Datatype that we're returning
retval_ptr	- Pointer to return value

Return values

0	- Success
-1	- Failure

int(* pipeline_interface_t::pipeline_setret_array) (void *state, int num, char **array)

Set an array as the return value for a pipeline function.

Parameters

state	- Script state
num	- Number of array arguments
array	- A string array of the array contents

Return values

0	- Success
-1	- Failure

int(* pipeline_interface_t::pipeline_setret_map) (void *state, int num, char **map_values)

Set a map as the return value for a pipeline function.

Parameters

state	- Script state
num	- Number of elements in map_values (keys and values)
map_values	- A string array of the map contents

The map_values parameter is arranged as follows:

• map_values[0] = key
• map_values[1] = value
• map_values[2] = key
• map_values[3] = value
• ...

Return values

0	- Success
-1	- Failure