Generic processor (PROC) module. More...

#include <stdarg.h>
#include <pthread.h>
#include <libmediaprocsutils/mem_utils.h>

Include dependency graph for proc.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	proc_ctx_s

Macros
#define	CJSON_PRINT(CJSON_PTR) cJSON_Print(CJSON_PTR)


#define	IPUT_PTS_ARRAY_SIZE 128

#define	IPUT_PTS_VAL 0

#define	IPUT_PTS_STC_VAL 1

Typedefs
typedef struct proc_if_s	proc_if_t

typedef struct log_ctx_s	log_ctx_t

typedef struct fifo_ctx_s	fifo_ctx_t

typedef struct fair_lock_s	fair_lock_t

typedef struct proc_frame_ctx_s	proc_frame_ctx_t

typedef struct interr_usleep_ctx_s	interr_usleep_ctx_t

typedef struct proc_ctx_s	proc_ctx_t

Enumerations
enum	proc_io_t { PROC_IPUT = 0, PROC_OPUT = 1, PROC_IO_NUM = 2 }

Functions
proc_ctx_t *	proc_open (const proc_if_t proc_if, const char settings_str, int proc_instance_index, uint32_t fifo_ctx_maxsize[PROC_IO_NUM], log_ctx_t *log_ctx, va_list arg)

void	proc_close (proc_ctx_t **ref_proc_ctx)

int	proc_send_frame (proc_ctx_t proc_ctx, const proc_frame_ctx_t proc_frame_ctx)

int	proc_recv_frame (proc_ctx_t proc_ctx, proc_frame_ctx_t *ref_proc_frame_ctx)

int	proc_opt (proc_ctx_t proc_ctx, const char tag,...)

int	proc_vopt (proc_ctx_t proc_ctx, const char tag, va_list arg)

int	proc_send_frame_default1 (proc_ctx_t proc_ctx, const proc_frame_ctx_t proc_frame_ctx)

int	proc_recv_frame_default1 (proc_ctx_t proc_ctx, proc_frame_ctx_t *ref_proc_frame_ctx)

void	proc_stats_register_accumulated_latency (proc_ctx_t *proc_ctx, const int64_t oput_frame_pts)

Detailed Description

Generic processor (PROC) module.

Author: Rafael Antoniello

A typical application would use a generic processor as follows:
1) Application prologue: Open the processor using function 'proc_open()' and obtain its context structure (or handler). Opening the processor is performed only once at the beginning of the application. Function 'proc_open()' will internally initialize and launch necessary processing threads.
2) Application cyclic: Launch a producer thread and a consumer thread for processing data. Use a control thread to manage processor run-time options. The producer should use 'proc_send_frame()' function to put new frames of data into the processor's input FIFO buffer. The consumer should use 'proc_recv_frame()' to obtain processed frames from the processor's output FIFO buffer. The control thread may use the function 'proc_opt()' to manage processor options.
3) Application epilogue: Close the processor using the function 'proc_close()'. Function 'proc_close()' internally joins the processing threads and release all related resources.

Concurrency: The processor (PROC) module is thread-safe, thus run-time functions can be executed concurrently (at the exception of 'proc_open()' and 'proc_close()' functions).

Definition in file proc.h.

Macro Definition Documentation

#define CJSON_PRINT ( CJSON_PTR ) cJSON_Print(CJSON_PTR)

cJSON to character string conversion function definition. String can be formated or minimized (removing whitespace, carriage return, ...).

Definition at line 70 of file proc.h.

#define IPUT_PTS_ARRAY_SIZE 128

Array registering the last input presentation time-stamps (PTS's). Each PTS is registered together with the system-time clock (STC) corresponding to the registration instant.

Definition at line 131 of file proc.h.

Typedef Documentation

typedef struct proc_ctx_s proc_ctx_t

Generic processor (PROC) context structure.

typedef struct proc_if_s proc_if_t

PROC interface structure prototype. Each PROC type will define a static and unambiguous interface of this type.

Definition at line 58 of file proc.h.

Enumeration Type Documentation

enum proc_io_t

Processor input-output type enumerator.

Definition at line 76 of file proc.h.

Function Documentation

void proc_close ( proc_ctx_t ** ref_proc_ctx )

Ends processing thread, de-initialize and release the generic processor (PROC) context structure and all the related resources.

Parameters

ref_proc_ctx Reference to the pointer to the processor (PROC) context structure to be release, that was obtained in a previous call to the 'proc_open()' function. Pointer is set to NULL on return.

Definition at line 208 of file proc.c.

proc_ctx_t* proc_open	(	const proc_if_t *	proc_if,
		const char *	settings_str,
		int	proc_instance_index,
		uint32_t	fifo_ctx_maxsize[PROC_IO_NUM],
		log_ctx_t *	log_ctx,
		va_list	arg
	)

Allocates generic processor (PROC) context structure, initializes, and launches processing thread.

Parameters

proc_if	Pointer to the processor interface structure (static and unambiguous interface of the type of processor we are opening).
settings_str	Character string containing initial settings for the processor. String format can be either a query-string or JSON.
proc_instance_index	Each PROC instance is registered in an instance array with a specific index (managed and assigned from outside this module). The idea behind using an array is to fetch as fast as possible the PROC instance to perform i/o operations.
fifo_ctx_maxsize	Maximum size, in number of queued elements, for the input and output FIFOs of the processor.
log_ctx	Pointer to the LOG module context structure.
arg	Variable list of parameters defined by user.

Returns: Pointer to the generic processor context structure on success, NULL if fails.

Definition at line 87 of file proc.c.

int proc_opt	(	proc_ctx_t *	proc_ctx,
		const char *	tag,
			...
	)

Processor options. This function is thread-safe and can be called concurrently.

Parameters

proc_ctx	Pointer to the processor (PROC) context structure obtained in a previous call to the 'proc_open()' function.
tag	Processor option tag, namely, option identifier string. The following options are available: PROC_UNBLOCK PROC_GET PROC_PUT
...	Variable list of parameters according to selected option. Refer to Tags description below to see the different additional parameters corresponding to each option tag.

Returns: Status code (STAT_SUCCESS code in case of success, for other code values please refer to .stat_codes.h).

Tags description (additional variable arguments per tag)

Tag "PROC_UNBLOCK":
Unblock processor input/output FIFO buffers.
No additional variable arguments are needed for calling function proc_opt() with this tag.

Tag "PROC_GET":
Get processor representational state (including current settings).
Additional variable arguments for function proc_opt() are:

Parameters

rest_fmt	Indicates the format in which the response data is to be returned. Available formats are enumerated at 'proc_if_rest_fmt_t'.
ref_reponse	Reference to the pointer to a data structure returning the processor's representational state. The returned data structure is formatted according to what is indicated in the parameter 'rest_fmt'.

Tag "PROC_PUT":
Put (pass) new settings to processor.
Additional variable arguments for function proc_opt() are:

Parameters

str	Pointer to a character string containing new settings for the processor. String format can be either a query-string or JSON.

Definition at line 368 of file proc.c.

int proc_recv_frame	(	proc_ctx_t *	proc_ctx,
		proc_frame_ctx_t **	ref_proc_frame_ctx
	)

Get new processed frame of data from the processor's output buffer. Unless unblocked (see processor options 'proc_opt()'), this function blocks until a new frame is available to be read from the processor's output buffer. This function is thread-safe and can be called concurrently.

Parameters

proc_ctx	Pointer to the processor (PROC) context structure obtained in a previous call to the 'proc_open()' function.
ref_proc_frame_ctx	Reference to the pointer to a structure characterizing the output processed frame. This function will return the processed frame passing its structure pointer by argument.

Returns: Status code (STAT_SUCCESS code in case of success, for other code values please refer to .stat_codes.h).

Definition at line 323 of file proc.c.

int proc_send_frame	(	proc_ctx_t *	proc_ctx,
		const proc_frame_ctx_t *	proc_frame_ctx
	)

Put new frame of data to be processed in the processor's input buffer. Unless unblocked (see processor options 'proc_opt()'), this function blocks until a slot is available to be able to push the new frame into the processor's input buffer. This function is thread-safe and can be called concurrently.

Parameters

proc_ctx	Pointer to the processor (PROC) context structure obtained in a previous call to the 'proc_open()' function.
proc_frame_ctx	Pointer to the structure characterizing the input frame to be processed. The frame is duplicated and inserted in the input buffer.

Returns: Status code (STAT_SUCCESS code in case of success, for other code values please refer to .stat_codes.h).

Definition at line 287 of file proc.c.

int proc_vopt	(	proc_ctx_t *	proc_ctx,
		const char *	tag,
		va_list	arg
	)

The function 'proc_vopt()' is the same as proc_opt() except that it is called with a va_list instead of a variable number of arguments. This function does not call the va_end macro. Because it invoke the va_arg macro, the value of the argument pointer is undefined after the call.

Definition at line 382 of file proc.c.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Tags description (additional variable arguments per tag)