Event Pool

Event Machine event pool related services. More...

Data Structures
union	em_pool_stats_opt_t
struct	em_pool_cfg_t
struct	em_pool_info_t
struct	em_pool_subpool_stats_t
struct	em_pool_stats_t
struct	em_pool_subpool_stats_selected_t
struct	em_pool_stats_selected_t

Functions
void	em_pool_cfg_init (em_pool_cfg_t *const pool_cfg)
em_pool_t	em_pool_create (const char *name, em_pool_t pool, const em_pool_cfg_t *pool_cfg)
em_status_t	em_pool_delete (em_pool_t pool)
em_pool_t	em_pool_find (const char *name)
size_t	em_pool_get_name (em_pool_t pool, char *name, size_t maxlen)
em_pool_t	em_pool_get_first (unsigned int *num)
em_pool_t	em_pool_get_next (void)
em_status_t	em_pool_info (em_pool_t pool, em_pool_info_t *pool_info)
void	em_pool_info_print (em_pool_t pool)
int	em_pool_get_num_subpools (em_pool_t pool)
	Return the number of subpools in an EM pool. More...
void	em_pool_info_print_all (void)
em_status_t	em_pool_stats (em_pool_t pool, em_pool_stats_t *pool_stats)
	Retrieve statistics about an EM pool. More...
em_status_t	em_pool_stats_reset (em_pool_t pool)
void	em_pool_stats_print (em_pool_t pool)
	Helper function to print statistics for an EM pool. More...
int	em_pool_subpool_stats (em_pool_t pool, const int subpools[], int num_subpools, em_pool_subpool_stats_t subpool_stats[])
	Retrieve statistics about subpool(s) of an EM pool. More...
em_status_t	em_pool_subpool_stats_reset (em_pool_t pool, const int subpools[], int num_subpools)
void	em_pool_subpool_stats_print (em_pool_t pool, const int subpools[], int num_subpools)
	Helper function to print statistics for subpool(s) of an EM pool. More...
em_status_t	em_pool_stats_selected (em_pool_t pool, em_pool_stats_selected_t *pool_stats, const em_pool_stats_opt_t *opt)
	Retrieve selected statistics about an EM pool. More...
void	em_pool_stats_selected_print (em_pool_t pool, const em_pool_stats_opt_t *opt)
	Helper function to print selected statistics for an EM pool. More...
int	em_pool_subpool_stats_selected (em_pool_t pool, const int subpools[], int num_subpools, em_pool_subpool_stats_selected_t subpool_stats[], const em_pool_stats_opt_t *opt)
	Retrieve selected statistics about subpool(s) of an EM pool. More...
void	em_pool_subpool_stats_selected_print (em_pool_t pool, const int subpools[], int num_subpools, const em_pool_stats_opt_t *opt)
	Helper function to print selected statistics for subpool(s) of an EM pool. More...
uint64_t	em_pool_to_u64 (em_pool_t pool)

Detailed Description

Event Machine event pool related services.

EM events are allocated from event pools with em_alloc() and freed back into them with em_free(). The event pools to be allocated from must first be created with em_pool_create().

Note that EM should always provide at least one pool, i.e. 'EM_POOL_DEFAULT' that can be used for event allocation. The default pool creation is platform specific: it can e.g. be done in 'em_init(conf)' with an appropriate default pool configuration, which is either given in the runtime config file through 'startup_pools' option or passed via the 'conf' (em_conf_t) parameter of em_init().

In addition to the default pool, startup pools configured in the runtime config file through option 'startup_pools' are also created during em_init().

Further event pools should be created explicitly with em_pool_create().

Event pool APIs for pool deletion, lookup, iteration etc. are listed below.

The 'em_pool_cfg_t' type given to em_pool_create() is HW/platform specific and is defined in event_machine_hw_types.h

Do not include this from the application, event_machine.h will do it for you.

Function Documentation

em_pool_cfg_init()

void em_pool_cfg_init

(

em_pool_cfg_t *const

pool_cfg

)

Initialize EM-pool configuration parameters for em_pool_create()

Initialize em_pool_cfg_t to default values for all fields. After initialization, the user further needs to update the fields of 'em_pool_cfg_t' with appropriate sizing information before calling em_pool_create().

Always initialize 'pool_cfg' first with em_pool_cfg_init(pool_cfg) to ensure backwards compatibility with potentially added new options.

Parameters

pool_cfg

Address of the em_pool_cfg_t to be initialized

See also

em_pool_cfg_t and em_pool_create()

Examples

bench_event.c, bench_pool.c, loop_vectors.c, pool_perf.c, and queue_types_ag.c.

Definition at line 43 of file event_machine_pool.c.

em_pool_create()

em_pool_t em_pool_create	(	const char *	name,
		em_pool_t	pool,
		const em_pool_cfg_t *	pool_cfg
	)

Create a new EM event pool

Create an EM event pool that can be used for event allocation. The event pool is created and configured according to the platform/HW specific em_pool_cfg_t given as argument.

Parameters

name	Pool name (optional, NULL ok)
pool	A specific pool handle to be used or EM_POOL_UNDEF to let EM decide (i.e. use a free handle).
pool_cfg	Pointer to the pool config

Returns

EM pool handle or EM_POOL_UNDEF on error

See also

em_pool_cfg_t and em_pool_cfg_init()

Examples

bench_event.c, loop_vectors.c, pool_perf.c, and queue_types_ag.c.

Definition at line 76 of file event_machine_pool.c.

em_pool_delete()

em_status_t em_pool_delete

(

em_pool_t

pool

)

Delete an existing EM event pool

Parameters

pool	EM event pool handle of the pool to be deleted.

Returns

EM_OK if successful

Examples

bench_event.c, loop_vectors.c, and queue_types_ag.c.

Definition at line 115 of file event_machine_pool.c.

em_pool_find()

em_pool_t em_pool_find

(

const char *

name

)

Find an EM event pool by name.

Finds a pool by the given name (exact match). An empty string will not match anything. The search is case sensitive. The function will return the first match only if there are duplicate names.

Parameters

name	the name to look for

Returns

pool handle or EM_POOL_UNDEF if not found

See also

em_pool_create()

Definition at line 127 of file event_machine_pool.c.

em_pool_get_first()

em_pool_t em_pool_get_first

(

unsigned int *

num

)

Initialize event pool iteration and return the first event pool handle.

Can be used to initialize the iteration to retrieve all created event pools for debugging or management purposes. Use em_pool_get_next() after this call until it returns EM_POOL_UNDEF. A new call to em_pool_get_first() resets the iteration, which is maintained per core (thread). The operation should be completed in one go before returning from the EO's event receive function (or start/stop).

The number of event pools (output arg 'num') may not match the amount of event pools actually returned by iterating using em_pool_get_next() if event pools are added or removed in parallel by another core. The order of the returned event pool handles is undefined.

unsigned int num;
em_pool_t pool = em_pool_get_first(&num);
while (pool != EM_POOL_UNDEF) {
   pool = em_pool_get_next();
}

Parameters

[out]

num

Pointer to an unsigned int to store the amount of event pools into

Returns

The first event pool handle or EM_POOL_UNDEF if none exist

See also

em_pool_get_next()

Definition at line 166 of file event_machine_pool.c.

em_pool_get_name()

size_t em_pool_get_name	(	em_pool_t	pool,
		char *	name,
		size_t	maxlen
	)

Get the name of an EM event pool.

A copy of the name string (up to 'maxlen' characters) is written to the user given buffer. The string is always null terminated, even if the given buffer length is less than the name length.

If the event pool has no name, the function returns 0 and writes an empty string.

Parameters

	pool	EM event pool
[out]	name	Destination buffer
	maxlen	Maximum length (including the terminating '0')

Returns

Number of characters written (excludes the terminating '0').

Examples

hello.c.

Definition at line 136 of file event_machine_pool.c.

em_pool_get_next()

em_pool_t em_pool_get_next

(

void

)

Return the next event pool handle.

Continues the event pool iteration started by em_pool_get_first() and returns the next event pool handle.

Returns

The next event pool handle or EM_POOL_UNDEF if the atomic group iteration is completed (i.e. no more event pools available).

See also

em_pool_get_first()

Definition at line 194 of file event_machine_pool.c.

em_pool_get_num_subpools()

int em_pool_get_num_subpools

(

em_pool_t

pool

)

Return the number of subpools in an EM pool.

Parameters

pool	EM pool handle

Returns

Number of subpools in the given pool(max=EM_MAX_SUBPOOLS) or -1 on error

Definition at line 293 of file event_machine_pool.c.

em_pool_info()

em_status_t em_pool_info	(	em_pool_t	pool,
		em_pool_info_t *	pool_info
	)

Retrieve information about an EM pool.

Parameters

	pool	EM pool handle
[out]	pool_info	Pointer to pool info that will be written

Returns

EM_OK if successful

Note

Set the 'available' or 'cache_available' in 'pool.statistics' of EM config file or in 'em_pool_cfg_t::stats_opt::opt' given to function em_pool_create(..., pool_cfg) to true for usage statistics, otherwise, only basic info is output omitting pool usage information (= all zeros).

Examples

bench_pool.c.

Definition at line 216 of file event_machine_pool.c.

em_pool_info_print()

void em_pool_info_print

(

em_pool_t

pool

)

Helper function to print EM Pool information for a given pool.

Uses em_pool_info() when printing the pool information.

Parameters

pool	EM pool handle

Note

Set the 'available' or 'cache_available' in 'pool.statistics' of EM config file or in 'em_pool_cfg_t::stats_opt::opt' given to function em_pool_create(..., pool_cfg) to true for usage statistics, otherwise, only basic info is printed, omitting pool usage information (= all zeros).

Examples

pool_perf.c.

Definition at line 287 of file event_machine_pool.c.

em_pool_info_print_all()

void em_pool_info_print_all

(

void

)

Helper function to print EM Pool information for all pools in the system.

Uses em_pool_info() when printing the pool information.

Note

Set the 'available' or 'cache_available' in 'pool.statistics' of EM config file or in 'em_pool_cfg_t::stats_opt::opt' given to function em_pool_create(..., pool_cfg) to true for usage statistics, otherwise, only basic info is printed, omitting pool usage information (= all zeros).

Definition at line 313 of file event_machine_pool.c.

em_pool_stats()

em_status_t em_pool_stats	(	em_pool_t	pool,
		em_pool_stats_t *	pool_stats
	)

Retrieve statistics about an EM pool.

Read the statistic counters enabled in 'em_pool_cfg_t::stats_opt' passed to em_pool_create() or in the 'pool.statistics' of EM config file. Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

	pool	EM pool handle
[out]	pool_stats	Pointer to pool statistics. A successful call writes to this pointer the requested pool statistics.

Returns

EM_OK if the statistics of all subpools of 'pool' are read successfully

Note

Runtime argument checking is not done unless EM_CHECK_LEVEL > 0.

See also

em_pool_cfg_t::stats_opt and em_pool_stats_t.

Examples

bench_pool.c.

Definition at line 327 of file event_machine_pool.c.

em_pool_stats_print()

void em_pool_stats_print

(

em_pool_t

pool

)

Helper function to print statistics for an EM pool.

Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

pool	EM pool handle

Uses em_pool_stats() when printing the pool statistics.

Definition at line 390 of file event_machine_pool.c.

em_pool_stats_reset()

em_status_t em_pool_stats_reset

(

em_pool_t

pool

)

Reset statistics for an EM pool.

Reset all statistic counters in 'em_pool_stats_t::subpool_stats' to zero except: 'em_pool_subpool_stats_t::available' 'em_pool_subpool_stats_t::cache_available',

Parameters

pool	EM Pool handle

Returns

EM_OK if successful

Definition at line 365 of file event_machine_pool.c.

em_pool_stats_selected()

em_status_t em_pool_stats_selected	(	em_pool_t	pool,
		em_pool_stats_selected_t *	pool_stats,
		const em_pool_stats_opt_t *	opt
	)

Retrieve selected statistics about an EM pool.

Read the selected statistic counters specified in 'em_pool_stats_opt_t'. The selected counters must have been enabled in 'em_pool_cfg_t::stats_opt' passed to em_pool_create() or in the 'pool.statistics' of EM config file. Values of the unselected counters are undefined. Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

	pool	EM pool handle
[out]	pool_stats	Pointer to pool statistics. A successful call writes to this pointer the requested pool statistics.
	opt	Used to select the statistic counters to read

Returns

EM_OK if the selected statistics of all subpools of 'pool' are read successfully

Note

Runtime argument checking is not done unless EM_CHECK_LEVEL > 0.

See also

em_pool_cfg_t::stats_opt, em_pool_stats_selected_t and em_pool_stats_opt_t.

Examples

bench_pool.c.

Definition at line 501 of file event_machine_pool.c.

em_pool_stats_selected_print()

void em_pool_stats_selected_print	(	em_pool_t	pool,
		const em_pool_stats_opt_t *	opt
	)

Helper function to print selected statistics for an EM pool.

Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

pool	EM pool handle
opt	Used to select the statistic counters to print

Uses em_pool_stats_selected() when printing the selected pool statistics.

Definition at line 546 of file event_machine_pool.c.

em_pool_subpool_stats()

int em_pool_subpool_stats	(	em_pool_t	pool,
		const int	subpools[],
		int	num_subpools,
		em_pool_subpool_stats_t	subpool_stats[]
	)

Retrieve statistics about subpool(s) of an EM pool.

Read the subpool statistic counters set in 'em_pool_cfg_t::stats_opt' passed to em_pool_create() or in the 'pool.statistics' of EM config file. Note that there may be some delay until performed pool operations are visible in the statistics.

The function returns the number of subpool statistics actually retrieved. A return value equal to 'num_subpools' means that the subpool statistics for given indices in 'subpools' are all retrieved successfully. A value less than 'num_subpools' means that the statistics for subpools whose indices are given at the end of 'subpools' can not be fetched. The function will not modify corresponding 'subpool_stats'.

Parameters

	pool	EM pool handle
	subpools	Array of subpool indices, must contain 'num_subpools' valid subpool-indices. 0 <= indices < number of subpools 'pool' has.
	num_subpools	Number of subpools to retrieve statistics for. 0 < num_subpools <= number of subpools 'pool' has.
[out]	subpool_stats	Array of subpool statistics, must have room for 'num_subpools' entries of subpool statistics. A successful call writes to this array the requested subpool statistics [out].

Returns

number of stats successfully fetched (equal to 'num_subpools' if all successful) or 0 on error.

em_pool_t pool = 1;
int num = 3;
int subpools[3] = [0, 3, 2];
em_pool_subpool_stats_t stats[3];
int ret = em_pool_subpool_stats(pool, subpools, num, stats);

The mapping between stats and subpools is as follows: stats[0] <-> subpools[0] stats[1] <-> subpools[1] ... stats[num_subpools - 1] <-> subpools[num_subpools - 1] So in above code, stats[1] stores statistics for the subpool whose index is 3.

Note

Runtime argument checking is not done unless EM_CHECK_LEVEL > 0.

See also

em_pool_cfg_t::stats_opt and em_pool_subpool_stats_t.

Examples

bench_pool.c.

Definition at line 399 of file event_machine_pool.c.

em_pool_subpool_stats_print()

void em_pool_subpool_stats_print	(	em_pool_t	pool,
		const int	subpools[],
		int	num_subpools
	)

Helper function to print statistics for subpool(s) of an EM pool.

Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

pool	EM pool handle
subpools	Array of subpool indices 0 <= indices < number of subpools pool has
num_subpools	Number of subpools to print statistics for 0 < num_subpools <= number of subpools pool has

Uses em_pool_subpool_stats() when printing the subpool statistics.

Definition at line 481 of file event_machine_pool.c.

em_pool_subpool_stats_reset()

em_status_t em_pool_subpool_stats_reset	(	em_pool_t	pool,
		const int	subpools[],
		int	num_subpools
	)

Reset statistics for subpool(s) of an EM pool.

Reset all statistics counters in given subpools of an EM pool to zero except: 'em_pool_subpool_stats_t::available' 'em_pool_subpool_stats_t::cache_available'

Parameters

pool	EM pool handle
subpools	Array of subpool indices 0 <= indices < number of subpools pool has
num_subpools	Number of subpools to reset statistics for 0 < num_subpools <= number of subpools pool has

Returns

EM_OK if successful

Definition at line 450 of file event_machine_pool.c.

em_pool_subpool_stats_selected()

int em_pool_subpool_stats_selected	(	em_pool_t	pool,
		const int	subpools[],
		int	num_subpools,
		em_pool_subpool_stats_selected_t	subpool_stats[],
		const em_pool_stats_opt_t *	opt
	)

Retrieve selected statistics about subpool(s) of an EM pool.

Read the selected subpool statistic counters given in 'em_pool_stats_opt_t'. The selected counters must have been enabled in 'em_pool_cfg_t::stats_opt' passed to em_pool_create() or in the 'pool.statistics' of EM config file. Values of the unselected counters are undefined. Note that there may be some delay until performed pool operations are visible in the statistics.

The function returns the number of selected subpool statistics actually read. A return value of 'num_subpools' means that the selected subpool statistics for the given indices in 'subpools' are all retrieved successfully. A value less than 'num_subpools' means that the selected statistics for subpools whose indices are given at the end of 'subpools' can not be fetched. The function will not modify corresponding 'subpool_stats'.

Parameters

	pool	EM pool handle
	subpools	Array of subpool indices, must contain 'num_subpools' valid subpool-indices. 0 <= indices < number of subpools 'pool' has.
	num_subpools	Number of subpools to retrieve statistics for. 0 < num_subpools <= number of subpools 'pool' has.
[out]	subpool_stats	Array of subpool statistics, must have room for 'num_subpools' entries of subpool statistics. A successful call writes to this array the requested subpool statistics [out].
	opt	Used to select the statistic counters to read

Returns

number of subpool_stats successfully fetched (equal to 'num_subpools' if all successful) or 0 on error.

em_pool_t pool = 1;
int num = 3;
int subpools[3] = [0, 3, 2];
em_pool_subpool_stats_selected_t stats[3];
em_pool_stats_opt_t opt = {.bit.available = 1};
int ret = em_pool_subpool_stats_selected(pool, subpools, num, stats, &opt);

The mapping between stats and subpools is as follows: stats[0] <-> subpools[0] stats[1] <-> subpools[1] ... stats[num_subpools - 1] <-> subpools[num_subpools - 1] So in above code, stats[1] stores selected statistics for the subpool whose index is 3.

Note

Runtime argument checking is not done unless EM_CHECK_LEVEL > 0.

See also

em_pool_cfg_t::stats_opt, em_pool_subpool_stats_selected_t and em_pool_stats_opt_t.

Examples

bench_pool.c.

Definition at line 554 of file event_machine_pool.c.

em_pool_subpool_stats_selected_print()

void em_pool_subpool_stats_selected_print	(	em_pool_t	pool,
		const int	subpools[],
		int	num_subpools,
		const em_pool_stats_opt_t *	opt
	)

Helper function to print selected statistics for subpool(s) of an EM pool.

Note that there may be some delay until performed pool operations are visible in the statistics.

Parameters

pool	EM pool handle
subpools	Array of subpool indices 0 <= indices < number of subpools pool has
num_subpools	Number of subpools to print statistics for 0 < num_subpools <= number of subpools pool has
opt	Used to select the statistic counters to print

Uses em_pool_subpool_stats_selected() when printing the selected subpool statistics.

Definition at line 612 of file event_machine_pool.c.

em_pool_to_u64()

uint64_t em_pool_to_u64

(

em_pool_t

pool

)

Convert an EM pool handle to an unsigned integer

Parameters

pool	EM pool handle to be converted

Returns

uint64_t value that can be used to print/display the handle

Note

This routine is intended to be used for diagnostic purposes to enable applications to e.g. generate a printable value that represents an em_pool_t handle.

Definition at line 619 of file event_machine_pool.c.