API Description

Setup threads/processes.

Data Structures
struct	odph_linux_thr_params_t
	Thread parameter for Linux pthreads and processes. More...

struct	odph_linux_pthread_t
	Linux pthread state information. More...

struct	odph_linux_process_t
	Linux process state information. More...

struct	odph_thread_param_t
	Thread parameters (pthreads and processes) More...

struct	odph_thread_start_args_t
	Helper internal thread start arguments. More...

struct	odph_thread_t
	Thread state information. More...

struct	odph_helper_options_t
	Linux helper options. More...

struct	odph_thread_common_param_t
	Common parameters for odph_thread_create() call. More...

struct	odph_thread_join_result_t
	Thread join result. More...

Functions
int	odph_linux_process_fork (odph_linux_process_t proc, int cpu, const odph_linux_thr_params_t thr_params)
	Fork a process. More...

int	odph_linux_process_fork_n (odph_linux_process_t proc_tbl, const odp_cpumask_t mask, const odph_linux_thr_params_t *thr_params)
	Fork a number of processes. More...

int	odph_linux_process_wait_n (odph_linux_process_t *proc_tbl, int num)
	Wait for a number of processes. More...

int	odph_linux_pthread_create (odph_linux_pthread_t pthread_tbl, const odp_cpumask_t mask, const odph_linux_thr_params_t *thr_params)
	Creates and launches pthreads. More...

void	odph_linux_pthread_join (odph_linux_pthread_t *thread_tbl, int num)
	Waits pthreads to exit. More...

void	odph_thread_param_init (odph_thread_param_t *param)
	Initialize thread params. More...

void	odph_thread_common_param_init (odph_thread_common_param_t *param)
	Initialize thread common params. More...

int	odph_thread_create (odph_thread_t thread[], const odph_thread_common_param_t *param, const odph_thread_param_t thr_param[], int num)
	Create and pin threads (as Linux pthreads or processes) More...

int	odph_thread_join (odph_thread_t thread[], int num)
	Wait previously launched threads to exit. More...

int	odph_thread_join_result (odph_thread_t thread[], odph_thread_join_result_t res[], int num)
	Wait previously launched threads to exit. More...

int	odph_odpthread_setaffinity (const int cpu)
	Set CPU affinity of the current odp thread. More...

int	odph_odpthread_getaffinity (void)
	Get CPU affinity of the current odp thread. More...

int	odph_parse_options (int argc, char *argv[])
	Parse linux helper options. More...

int	odph_options (odph_helper_options_t *options)
	Get linux helper options. More...

Function Documentation

◆ odph_linux_process_fork()

int odph_linux_process_fork	(	odph_linux_process_t *	proc,
		int	cpu,
		const odph_linux_thr_params_t *	thr_params
	)

Fork a process.

Forks and sets CPU affinity for the child process. Ignores 'start' and 'arg' thread parameters.

Parameters

[out]	proc	Pointer to process state info (for output)
	cpu	Destination CPU for the child process
	thr_params	Linux helper thread parameters

Returns: On success: 1 for the parent, 0 for the child On failure: -1 for the parent, -2 for the child

Deprecated:: Use odph_thread_create() instead.

◆ odph_linux_process_fork_n()

int odph_linux_process_fork_n	(	odph_linux_process_t *	proc_tbl,
		const odp_cpumask_t *	mask,
		const odph_linux_thr_params_t *	thr_params
	)

Fork a number of processes.

Forks and sets CPU affinity for child processes. Ignores 'start' and 'arg' thread parameters.

Parameters

[out]	proc_tbl	Process state info table (for output)
	mask	CPU mask of processes to create
	thr_params	Linux helper thread parameters

Returns: On success: 1 for the parent, 0 for the child On failure: -1 for the parent, -2 for the child

Deprecated:: Use odph_thread_create() instead.

◆ odph_linux_process_wait_n()

int odph_linux_process_wait_n	(	odph_linux_process_t *	proc_tbl,
		int	num
	)

Wait for a number of processes.

Waits for a number of child processes to terminate. Records process state change status into the process state info structure.

Parameters

proc_tbl	Process state info table (previously filled by fork)
num	Number of processes to wait

Returns: 0 on success, -1 on failure

Deprecated:: Use odph_thread_join() instead.

◆ odph_linux_pthread_create()

int odph_linux_pthread_create	(	odph_linux_pthread_t *	pthread_tbl,
		const odp_cpumask_t *	mask,
		const odph_linux_thr_params_t *	thr_params
	)

Creates and launches pthreads.

Creates, pins and launches threads to separate CPU's based on the cpumask.

Parameters

[out]	pthread_tbl	Table of pthread state information records. Table must have at least as many entries as there are CPUs in the CPU mask.
	mask	CPU mask
	thr_params	Linux helper thread parameters

Returns: Number of threads created

Deprecated:: Use odph_thread_create() instead.

◆ odph_linux_pthread_join()

void odph_linux_pthread_join	(	odph_linux_pthread_t *	thread_tbl,
		int	num
	)

Waits pthreads to exit.

Returns when all threads have been exit.

Parameters

thread_tbl	Thread table
num	Number of threads to create

Deprecated:: Use odph_thread_join() instead.

◆ odph_thread_param_init()

void odph_thread_param_init ( odph_thread_param_t * param )

Initialize thread params.

Initialize an odph_thread_param_t to its default values for all fields.

Parameters

[out] param Pointer to parameter structure

◆ odph_thread_common_param_init()

void odph_thread_common_param_init ( odph_thread_common_param_t * param )

Initialize thread common params.

Initialize an odph_thread_common_param_t to its default values for all fields.

Parameters

[out] param Pointer to parameter structure

◆ odph_thread_create()

int odph_thread_create	(	odph_thread_t	thread[],
		const odph_thread_common_param_t *	param,
		const odph_thread_param_t	thr_param[],
		int	num
	)

Create and pin threads (as Linux pthreads or processes)

Function may be called multiple times to create threads in steps. Each call launches 'num' threads and pins those to separate CPUs based on the cpumask. Use 'thread_model' parameter to select if Linux pthreads or processes are used. This selection may be overridden with ODP helper options. See e.g. –odph_proc under odph_options() documentation.

Thread creation may be synchronized by setting 'sync' parameter. It serializes thread start up (odp_init_local() calls), which helps to stabilize application start up sequence.

By default, the thread parameter table contains 'num' elements, one for each thread to be created. However, all threads may be created with a single thread parameter table element by setting 'share_param' parameter.

Use odph_thread_common_param_init() and odph_thread_param_init() to initialize parameters with default values.

Thread table must be large enough to hold 'num' elements. Also the cpumask must contain 'num' CPUs. Threads are pinned to CPUs in order - the first thread goes to the smallest CPU number of the mask, etc.

Launched threads may be waited for exit with odph_thread_join(), or with direct Linux system calls. If odph_thread_join() is used, the output thread table elements must not be modified during the life time of the threads.

Parameters

[out]	thread	Thread table for output
	param	Common parameters for all threads to be created
	thr_param	Table of thread parameters
	num	Number of threads to create

Returns: Number of threads created

Return values

-1	On failure

See also: odph_thread_join()

◆ odph_thread_join()

int odph_thread_join	(	odph_thread_t	thread[],
		int	num
	)

Wait previously launched threads to exit.

Function waits for threads launched with odph_thread_create() to exit. Threads may be waited to exit in a different order than those were created. A function call may be used to wait any number of launched threads to exit. A particular thread may be waited only once.

Threads are joined in the order they are in 'thread' table. Returns on the first non-zero exit status or other failure.

Parameters

thread	Table of threads to exit
num	Number of threads to exit

Returns: Number of threads successfully joined with zero exit status (0 ... num)

Return values

-1	On failure

See also: odph_thread_create()

◆ odph_thread_join_result()

int odph_thread_join_result	(	odph_thread_t	thread[],
		odph_thread_join_result_t	res[],
		int	num
	)

Wait previously launched threads to exit.

Similar to odph_thread_join() but outputs results of joined threads and stops only if the actual join operation fails for some thread. Threads are joined in the order they are in 'thread' table. Returns number of threads successfully joined and writes respective exit statuses into the 'res' table.

Parameters

	thread	Table of threads to exit
[out]	res	Table for result output
	num	Number of threads to exit and results to output

Returns: Number of threads successfully joined (0 ... num)

Return values

-1	On failure

See also: odph_thread_create()

◆ odph_odpthread_setaffinity()

int odph_odpthread_setaffinity ( const int cpu )

Set CPU affinity of the current odp thread.

CPU affinity determines the CPU core on which the thread is eligible to run.

Parameters

cpu	The affinity CPU core

Returns: 0 on success, -1 on failure

◆ odph_odpthread_getaffinity()

int odph_odpthread_getaffinity ( void )

Get CPU affinity of the current odp thread.

CPU affinity determines the CPU core on which the thread is eligible to run.

Returns: positive cpu ID on success, -1 on failure

◆ odph_parse_options()

int odph_parse_options	(	int	argc,
		char *	argv[]
	)

Parse linux helper options.

Parse the command line options. Pick up (–odph_ prefixed) options meant for the helper itself. When helper options are found, those are removed from argv[] and remaining options are packed to the beginning of the array.

Currently supported options
Command line	Environment variable	Description
–odph_proc	ODPH_PROC_MODE	When defined, threads are Linux processes. Otherwise, pthreads are used instead.

This function may be called before ODP initialization.

Parameters

argc	Argument count
argv	Argument vector

Returns: New argument count. Original argument count decremented by the number of removed helper options.

◆ odph_options()

int odph_options ( odph_helper_options_t * options )

Get linux helper options.

Return used ODP helper options. odph_parse_options() must be called before using this function.

This function may be called before ODP initialization.

Parameters

[out] options ODP helper options

Returns: 0 on success, -1 on failure

API Description

Data Structures

Functions

Function Documentation

◆ odph_linux_process_fork()

◆ odph_linux_process_fork_n()

◆ odph_linux_process_wait_n()

◆ odph_linux_pthread_create()

◆ odph_linux_pthread_join()

◆ odph_thread_param_init()

◆ odph_thread_common_param_init()

◆ odph_thread_create()

◆ odph_thread_join()

◆ odph_thread_join_result()

◆ odph_odpthread_setaffinity()

◆ odph_odpthread_getaffinity()

◆ odph_parse_options()

◆ odph_options()