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...
struct	pipeline_module_const_t
	List of library constants to be registered. More...
struct	pipeline_module_func_t
	List of library functions to be registered. 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_register_library )(const char *libname, const pipeline_module_func_t *funcs, const pipeline_module_const_t *constants)
	Make a library of functions and constants available to a pipeline. 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)

To call this function from a JavaScript module do this

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

or

var 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 which is owned by the pipeline
PIPELINE_COUNTER	An integer value protected by a semaphore
PIPELINE_NULL	Null return value (for return values)
PIPELINE_ARRAY	0 (or 1) based array
PIPELINE_MAP	A complex object
PIPELINE_BOOLEAN	A boolean type
PIPELINE_DSDATA_NO_FREE	A dsdata argument which is owned by the caller

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

Deprecated:

Use pipeline_generate_with_log()

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 or the length of the char** array created for PIPELINE_ARRAY and PIPELINE_MAP
-1	- Failure

Note

Returned values for all types but ARRAY and MAP should not be free()'d. They will be released on return from the function. Array and MAP are handled differently. In order to obtain an array or a map from a script a pointer to a char** needs to be passed in and the array elements as well as as the array need to be freed up when they aren't needed any longer.

A map will be represented as a char** where every even index is a key and every odd index a value.

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 (PIPELINE_NUMBER, PIPELINE_FLOAT, PIPELINE_STRING)
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_register_library) (const char *libname, const pipeline_module_func_t *funcs, const pipeline_module_const_t *constants)

Make a library of functions and constants available to a pipeline.

Parameters

libname	- Name of the library
funcs	- Function names and function pointers information

See also

pipeline_module_func_t. NULL if no functions to register.

Parameters

constants

- Contstant names and values.

See also

pipeline_module_const_t. NULL if no constants to register.

Return values

0	- Success
-1	- Failure

A library of functions and/or constants 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