Heka sandbox implementation. More...

#include <stdbool.h>
#include <time.h>
#include "../../luasandbox.h"
#include "../error.h"
#include "../util/heka_message.h"
#include "../lauxlib.h"
#include "../lua.h"

Include dependency graph for sandbox.h:

Go to the source code of this file.

Classes
struct	lsb_heka_stats

Macros
#define	LSB_HEKA_EXPORT

#define	LSB_HEKA_MAX_MESSAGE_SIZE "max_message_size"

#define	LSB_HEKA_UPDATE_CHECKPOINT "update_checkpoint"

#define	LSB_HEKA_THIS_PTR "lsb_heka_this_ptr"

Typedefs
typedef struct lsb_heka_sandbox	lsb_heka_sandbox

typedef struct lsb_heka_stats	lsb_heka_stats

typedef int(*	lsb_heka_im_input) (void parent, const char pb, size_t pb_len, double cp_numeric, const char *cp_string)
	inject_message callback function provided by the host. More...

typedef int(*	lsb_heka_im_analysis) (void parent, const char pb, size_t pb_len)
	inject_message callback function provided by the host. More...

typedef int(*	lsb_heka_update_checkpoint) (void parent, void sequence_id)
	update_checkpoint callback function provided by the host. More...

Enumerations
enum	lsb_heka_pm_rv { LSB_HEKA_PM_SENT = 0, LSB_HEKA_PM_FAIL = -1, LSB_HEKA_PM_SKIP = -2, LSB_HEKA_PM_RETRY = -3, LSB_HEKA_PM_BATCH = -4, LSB_HEKA_PM_ASYNC = -5 }

enum	lsb_heka_im_rv { LSB_HEKA_IM_SUCCESS = 0, LSB_HEKA_IM_ERROR = 1, LSB_HEKA_IM_CHECKPOINT = 2, LSB_HEKA_IM_LIMIT = 3 }

Functions
LSB_HEKA_EXPORT lsb_heka_sandbox *	lsb_heka_create_input (void parent, const char lua_file, const char state_file, const char lsb_cfg, lsb_logger *logger, lsb_heka_im_input im)
	Create a sandbox supporting the Heka Input Plugin API. More...

LSB_HEKA_EXPORT int	lsb_heka_pm_input (lsb_heka_sandbox hsb, double cp_numeric, const char cp_string, bool profile)
	Host access to the input sandbox process_message API. More...

LSB_HEKA_EXPORT lsb_heka_sandbox *	lsb_heka_create_analysis (void parent, const char lua_file, const char state_file, const char lsb_cfg, lsb_logger *logger, lsb_heka_im_analysis im)
	Create a sandbox supporting the Heka Analysis Plugin API. More...

LSB_HEKA_EXPORT int	lsb_heka_pm_analysis (lsb_heka_sandbox hsb, lsb_heka_message msg, bool profile)
	Host access to the analysis sandbox process_message API. More...

LSB_HEKA_EXPORT lsb_heka_sandbox *	lsb_heka_create_output (void parent, const char lua_file, const char state_file, const char lsb_cfg, lsb_logger *logger, lsb_heka_update_checkpoint ucp)
	Create a sandbox supporting the Heka Output Plugin API. More...

LSB_HEKA_EXPORT lsb_heka_sandbox *	lsb_heka_create_output_im (void parent, const char lua_file, const char state_file, const char lsb_cfg, lsb_logger *logger, lsb_heka_update_checkpoint ucp, lsb_heka_im_analysis im)
	Create a sandbox supporting the Heka Output Plugin API with inject_message support. More...

LSB_HEKA_EXPORT int	lsb_heka_pm_output (lsb_heka_sandbox hsb, lsb_heka_message msg, void *sequence_id, bool profile)
	Host access to the output sandbox process_message API. More...

LSB_HEKA_EXPORT void	lsb_heka_stop_sandbox_clean (lsb_heka_sandbox *hsb)
	Requests a long running input sandbox to stop. More...

LSB_HEKA_EXPORT void	lsb_heka_stop_sandbox (lsb_heka_sandbox *hsb)
	Aborts the running sandbox from a different thread of execution. More...

LSB_HEKA_EXPORT void	lsb_heka_terminate_sandbox (lsb_heka_sandbox hsb, const char err)
	Terminates the sandbox as if it had a fatal error (not thread safe). More...

LSB_HEKA_EXPORT char *	lsb_heka_destroy_sandbox (lsb_heka_sandbox *hsb)
	Frees all memory associated with the sandbox; hsb cannont be used after this point and the host should set it to NULL. More...

LSB_HEKA_EXPORT int	lsb_heka_timer_event (lsb_heka_sandbox *hsb, time_t t, bool shutdown)
	Host access to the timer_event API. More...

LSB_HEKA_EXPORT const char *	lsb_heka_get_error (lsb_heka_sandbox *hsb)
	Return the last error in human readable form. More...

LSB_HEKA_EXPORT const char *	lsb_heka_get_lua_file (lsb_heka_sandbox *hsb)
	Returns the filename of the Lua source. More...

LSB_HEKA_EXPORT lsb_heka_stats	lsb_heka_get_stats (lsb_heka_sandbox *hsb)
	Retrieve the sandbox profiling/monitoring statistics. More...

LSB_HEKA_EXPORT bool	lsb_heka_is_running (lsb_heka_sandbox *hsb)
	Convenience function to test if a sandbox is running. More...

LSB_HEKA_EXPORT lsb_state	lsb_heka_get_state (lsb_heka_sandbox *hsb)
	Queries the state of the sandbox. More...

LSB_HEKA_EXPORT const lsb_heka_message *	lsb_heka_get_message (lsb_heka_sandbox *hsb)
	Retrieve the currently active sandbox message. More...

LSB_HEKA_EXPORT char	lsb_heka_get_type (lsb_heka_sandbox *hsb)
	Retrieve the sandbox type. More...

Variables
LSB_HEKA_EXPORT lsb_err_id	LSB_ERR_HEKA_INPUT

Detailed Description

Heka sandbox implementation.

Definition in file sandbox.h.

Macro Definition Documentation

#define LSB_HEKA_EXPORT

Definition at line 29 of file sandbox.h.

#define LSB_HEKA_MAX_MESSAGE_SIZE "max_message_size"

Definition at line 33 of file sandbox.h.

#define LSB_HEKA_THIS_PTR "lsb_heka_this_ptr"

Definition at line 35 of file sandbox.h.

#define LSB_HEKA_UPDATE_CHECKPOINT "update_checkpoint"

Definition at line 34 of file sandbox.h.

Typedef Documentation

typedef int(* lsb_heka_im_analysis) (void *parent, const char *pb, size_t pb_len)

inject_message callback function provided by the host.

Parameters

parent	Opaque pointer the host object owning this sandbox.
pb	Pointer to a Heka protobuf encoded message being injected.
len	Length of pb_len

Returns: 0 on success

Definition at line 113 of file sandbox.h.

typedef int(* lsb_heka_im_input) (void *parent, const char *pb, size_t pb_len, double cp_numeric, const char *cp_string)

inject_message callback function provided by the host.

Only one (or neither) of the checkpoint values will be set in a call. Numeric checkpoints can have a measurable performance benefit but are not always applicable so both options are provided to support various types of input plugins. This function can be called with a NULL pb pointer by the 'is_running' API or if only a checkpoint update is being performed; it should be treated as a no-op and used as a synchronization point to collect statistics and communicate shutdown status.

Parameters

parent	Opaque pointer the host object owning this sandbox
pb	Pointer to a Heka protobuf encoded message being injected.
pb_en	Length of s
cp_numeric	Numeric based checkpoint (can be NAN)
cp_string	String based checkpoint (can be NULL)

Returns: 0 on success

Definition at line 98 of file sandbox.h.

typedef struct lsb_heka_sandbox lsb_heka_sandbox

Definition at line 53 of file sandbox.h.

typedef struct lsb_heka_stats lsb_heka_stats

typedef int(* lsb_heka_update_checkpoint) (void *parent, void *sequence_id)

update_checkpoint callback function provided by the host.

Parameters

parent	Opaque pointer the host object owning this sandbox.
sequence_id	Opaque pointer to the host message sequencing (passed into process_message).

Returns: 0 on success

Definition at line 126 of file sandbox.h.

Enumeration Type Documentation

enum lsb_heka_im_rv

Enumerator
LSB_HEKA_IM_SUCCESS
LSB_HEKA_IM_ERROR
LSB_HEKA_IM_CHECKPOINT
LSB_HEKA_IM_LIMIT

Definition at line 46 of file sandbox.h.

enum lsb_heka_pm_rv

Enumerator
LSB_HEKA_PM_SENT
LSB_HEKA_PM_FAIL
LSB_HEKA_PM_SKIP
LSB_HEKA_PM_RETRY
LSB_HEKA_PM_BATCH
LSB_HEKA_PM_ASYNC

Definition at line 37 of file sandbox.h.

Function Documentation

LSB_HEKA_EXPORT lsb_heka_sandbox* lsb_heka_create_analysis	(	void *	parent,
		const char *	lua_file,
		const char *	state_file,
		const char *	lsb_cfg,
		lsb_logger *	logger,
		lsb_heka_im_analysis	im
	)

Create a sandbox supporting the Heka Analysis Plugin API.

Parameters

parent	Opaque pointer the host object owning this sandbox
lua_file	Fully qualified filename to the Lua source file
state_file	Fully qualified filename to the state preservation file (NULL if no preservation is required)
lsb_cfg	Full configuration string as a Lua table (NULL for lsb defaults)
logger	Struct for error reporting/debug printing (NULL to disable)
im	inject_message callback

Returns: lsb_heka_sandbox* On success a pointer to the sandbox otherwise NULL

LSB_HEKA_EXPORT lsb_heka_sandbox* lsb_heka_create_input	(	void *	parent,
		const char *	lua_file,
		const char *	state_file,
		const char *	lsb_cfg,
		lsb_logger *	logger,
		lsb_heka_im_input	im
	)

Create a sandbox supporting the Heka Input Plugin API.

Parameters

parent	Opaque pointer the host object owning this sandbox
lua_file	Fully qualified path to the Lua source file
state_file	Fully qualified filename to the state preservation file (NULL if no preservation is required)
lsb_cfg	Full configuration string as a Lua table (NULL for lsb defaults)
logger	Struct for error reporting/debug printing (NULL to disable)
im	inject_message callback

Returns: lsb_heka_sandbox* On success a pointer to the sandbox otherwise NULL

LSB_HEKA_EXPORT lsb_heka_sandbox* lsb_heka_create_output	(	void *	parent,
		const char *	lua_file,
		const char *	state_file,
		const char *	lsb_cfg,
		lsb_logger *	logger,
		lsb_heka_update_checkpoint	ucp
	)

Create a sandbox supporting the Heka Output Plugin API.

Parameters

parent	Opaque pointer the host object owning this sandbox
lua_file	Fully qualified path to the Lua source file
state_file	Fully qualified filename to the state preservation file (NULL if no preservation is required)
lsb_cfg	Full configuration string as a Lua table (NULL for lsb defaults)
logger	Struct for error reporting/debug printing (NULL to disable)
ucp	checkpoint_updated callback when using batch or async output

Returns: lsb_heka_sandbox* On success a pointer to the sandbox otherwise NULL

LSB_HEKA_EXPORT lsb_heka_sandbox* lsb_heka_create_output_im	(	void *	parent,
		const char *	lua_file,
		const char *	state_file,
		const char *	lsb_cfg,
		lsb_logger *	logger,
		lsb_heka_update_checkpoint	ucp,
		lsb_heka_im_analysis	im
	)

Create a sandbox supporting the Heka Output Plugin API with inject_message support.

Parameters

parent	Opaque pointer the host object owning this sandbox
lua_file	Fully qualified path to the Lua source file
state_file	Fully qualified filename to the state preservation file (NULL if no preservation is required)
lsb_cfg	Full configuration string as a Lua table (NULL for lsb defaults)
logger	Struct for error reporting/debug printing (NULL to disable)
ucp	checkpoint_updated callback when using batch or async output
im	inject_message callback

Returns: lsb_heka_sandbox* On success a pointer to the sandbox otherwise NULL

LSB_HEKA_EXPORT char* lsb_heka_destroy_sandbox ( lsb_heka_sandbox * hsb )

Frees all memory associated with the sandbox; hsb cannont be used after this point and the host should set it to NULL.

Parameters

hsb	Heka sandbox to free

Returns: NULL on success, pointer to an error message on failure that MUST BE FREED by the caller.

LSB_HEKA_EXPORT const char* lsb_heka_get_error ( lsb_heka_sandbox * hsb )

Return the last error in human readable form.

Parameters

hsb	Heka sandbox

Returns: const char* error message

LSB_HEKA_EXPORT const char* lsb_heka_get_lua_file ( lsb_heka_sandbox * hsb )

Returns the filename of the Lua source.

Parameters

hsb	Heka sandbox

Returns: const char* filename.

LSB_HEKA_EXPORT const lsb_heka_message* lsb_heka_get_message ( lsb_heka_sandbox * hsb )

Retrieve the currently active sandbox message.

This call returns a handle to internal data and is not thread safe.

Parameters

hsb Heka sandbox

Returns
const lsb_heka_message* NULL if there is no active message

LSB_HEKA_EXPORT lsb_state lsb_heka_get_state ( lsb_heka_sandbox * hsb )

Queries the state of the sandbox.

Parameters

hsb

Returns: lsb_state

LSB_HEKA_EXPORT lsb_heka_stats lsb_heka_get_stats ( lsb_heka_sandbox * hsb )

Retrieve the sandbox profiling/monitoring statistics.

This call accesses internal data and is not thread safe.

Parameters

hsb	Heka sandbox

Returns: lsb_heka_stats A copy of the stats structure

LSB_HEKA_EXPORT char lsb_heka_get_type ( lsb_heka_sandbox * hsb )

Retrieve the sandbox type.

Parameters

hsb Heka sandbox

Returns
char Heka sandbox type identifer

LSB_HEKA_EXPORT bool lsb_heka_is_running ( lsb_heka_sandbox * hsb )

Convenience function to test if a sandbox is running.

Parameters

hsb	Heka sandbox

Returns: True if the sandbox has not been terminated

LSB_HEKA_EXPORT int lsb_heka_pm_analysis	(	lsb_heka_sandbox *	hsb,
		lsb_heka_message *	msg,
		bool	profile
	)

Host access to the analysis sandbox process_message API.

Parameters

hsb	Heka analysis sandbox
msg	Heka message to process
profile	Take a timing sample on this execution

Returns: int >0 fatal error 0 success <0 non-fatal error (status message is logged)

LSB_HEKA_EXPORT int lsb_heka_pm_input	(	lsb_heka_sandbox *	hsb,
		double	cp_numeric,
		const char *	cp_string,
		bool	profile
	)

Host access to the input sandbox process_message API.

If a numeric checkpoint is set the string checkpoint is ignored.

Parameters

hsb	Heka input sandbox
cp_numeric	NAN if no numeric checkpoint
cp_string	NULL if no string checkpoint
profile	Take a timing sample on this execution

Returns: int >0 fatal error 0 success <0 non-fatal error (status message is logged)

LSB_HEKA_EXPORT int lsb_heka_pm_output	(	lsb_heka_sandbox *	hsb,
		lsb_heka_message *	msg,
		void *	sequence_id,
		bool	profile
	)

Host access to the output sandbox process_message API.

Parameters

hsb	Heka output sandbox
msg	Heka message to process
sequence_id	Opaque pointer to the message sequence id (only used for async output plugin otherwise it should be NULL)
profile	Take a timing sample on this execution

Returns: int >0 fatal error 0 success -1 non-fatal_error (status message is logged) -2 skip -3 retry -4 batching -5 async output

LSB_HEKA_EXPORT void lsb_heka_stop_sandbox ( lsb_heka_sandbox * hsb )

Aborts the running sandbox from a different thread of execution.

A "shutting down" termination message is generated. Used to abort long runnning sandboxes such as an input sandbox.

Parameters

hsb	Heka sandbox to forcibly stop

Returns

LSB_HEKA_EXPORT void lsb_heka_stop_sandbox_clean ( lsb_heka_sandbox * hsb )

Requests a long running input sandbox to stop.

This call is not thread safe.

Parameters

hsb	Heka sandbox to cleanly stop

Returns

LSB_HEKA_EXPORT void lsb_heka_terminate_sandbox	(	lsb_heka_sandbox *	hsb,
		const char *	err
	)

Terminates the sandbox as if it had a fatal error (not thread safe).

Parameters

hsb	Heka sandbox to terminate
err	Reason for termination

LSB_HEKA_EXPORT int lsb_heka_timer_event	(	lsb_heka_sandbox *	hsb,
		time_t	t,
		bool	shutdown
	)

Host access to the timer_event API.

Parameters

hsb	Heka sandbox
t	Clock time of the timer_event execution
shutdown	Flag indicating the Host is shutting down allowing the sandbox to do any desired finialization)

Returns: int 0 on success

Variable Documentation

LSB_HEKA_EXPORT lsb_err_id LSB_ERR_HEKA_INPUT

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation