#include <event_machine_queue.h>

Collaboration diagram for em_queue_param_t:

[legend]

Data Fields
em_queue_t	queue

em_queue_type_t	type

em_queue_prio_t	prio

em_queue_group_t	queue_group

em_atomic_group_t	atomic_group

em_queue_flag_t	flags

unsigned int	min_events

em_output_queue_conf_t	output_conf

uint32_t	num_aggr

em_queue_aggr_conf_t *	aggr_conf

uint32_t	__internal_check

Detailed Description

EM queue creation parameters.

Used with em_queue_create_param() and is able to replace several queue-create APIs including: em_queue_create(), em_queue_create_static(), em_queue_create_ag() and em_queue_create_static_ag().

Note: em_queue_param_init() must be called to initialize the parameters to default values before filling in the desired values and calling em_queue_create_param() to ensure backwards compatibility with potentially added new options. EM will enforce this and report an error if not done.

Create scheduled atomic, parallel or ordered queues by using the '.type' values EM_QUEUE_TYPE_ATOMIC, EM_QUEUE_TYPE_PARALLEL or EM_QUEUE_TYPE_ORDERED.

To create an unscheduled queue, use the '.type' EM_QUEUE_TYPE_UNSCHEDULED. The '.prio' and '.queue_group' are not relevant, but need to be set to EM_QUEUE_PRIO_UNDEF and EM_QUEUE_GROUP_UNDEF. Unscheduled queues can't be associated with an EO (em_eo_add_queue() fails).

To create a local queue, use '.type' EM_QUEUE_TYPE_LOCAL. The '.queue_group' is not relevant and must be set to EM_QUEUE_GROUP_UNDEF. The virtual local queue is created for all cores in this EM instance. Note also that the implementation may not implement (all) priorities for local queues.

To create an output queue (i.e. output from EM), use the '.type' EM_QUEUE_TYPE_OUTPUT. Pass the needed information via the '.output_conf' field. The '.queue_group' is not relevant and must be set to EM_QUEUE_GROUP_UNDEF. Note also that the implementation may not implement priorities for output queues.

em_queue_param_t param;
em_queue_aggr_conf_t aggr_conf[num_aggr];  (optional)
 
em_queue_param_init(&param);
em_queue_aggr_conf_init(num_aggr, aggr_conf);
 
param.type = EM_QUEUE_TYPE_ATOMIC;
...
 
for (i = 0; i < num_aggr; i++) {
    aggr_conf[i].pool = my_vector_pool;
    ...
}
param.num_aggr = num_aggr;
param.aggr_conf = aggr_conf;
...
queue = em_queue_create_param("my-queue", &param);

Definition at line 699 of file event_machine_queue.h.

Field Documentation

◆ __internal_check

uint32_t em_queue_param_t::__internal_check

Internal check - don't touch!

EM will verify that em_queue_param_init(param) has been called before use.

Definition at line 806 of file event_machine_queue.h.

◆ aggr_conf

em_queue_aggr_conf_t* em_queue_param_t::aggr_conf

Aggregator queue configuration parameters

When 'num_aggr' is non-zero, 'aggr_conf' must point to an array of size 'num_aggr'.

The 'aggr_conf' array, if given, must be initialized with em_queue_aggr_conf_init(num_aggr, aggr_conf) before setting fields to ensure compatibility with potentially added new options.

The default value is null.

Definition at line 798 of file event_machine_queue.h.

◆ atomic_group

em_atomic_group_t em_queue_param_t::atomic_group

Atomic group for the queue, only use when wanting the new queue to be part of an existing atomic group (see the EM atomic group APIs). Note: can only be used when .type = EM_QUEUE_TYPE_ATOMIC. Set to EM_ATOMIC_GROUP_UNDEF by em_queue_param_init(), but the user needs to change it to a valid atomic group, or EM_ATOMIC_GROUP_UNDEF if not relevant for the queue.

Definition at line 745 of file event_machine_queue.h.

◆ flags

em_queue_flag_t em_queue_param_t::flags

Extra flags. See em_queue_flag_t for choices. EM_QUEUE_FLAG_DEFAULT indicates a default multithread-safe queue without any special guarantees. Set to EM_QUEUE_FLAG_DEFAULT by em_queue_param_init().

Definition at line 753 of file event_machine_queue.h.

◆ min_events

unsigned int em_queue_param_t::min_events

Request for a minimum amount of events the queue can hold or use 0 for the EM default value. Queue creation will fail, if the system cannot support the requested amount. Set to 0 by em_queue_param_init().

Definition at line 761 of file event_machine_queue.h.

◆ num_aggr

uint32_t em_queue_param_t::num_aggr

Number of aggregator queues to create for this queue, use zero (0) for no aggregation.

Aggregator queues try to aggregate multiple events into vector events before enqueuing to the 'parent' queue.

Two events enqueued through different aggregators may appear in any order when dequeued.

When >= 1, configuration must be provided for each aggregator through the 'aggr_conf' array. Must be smaller or equal to EM_QUEUE_MAX_AGGR.

The default value is zero.

Definition at line 785 of file event_machine_queue.h.

◆ output_conf

em_output_queue_conf_t em_queue_param_t::output_conf

EM output queue configuration. Only evaluated when .type = EM_QUEUE_TYPE_OUTPUT.

Definition at line 767 of file event_machine_queue.h.

◆ prio

em_queue_prio_t em_queue_param_t::prio

Queue priority, mandatory for certain queue types. Set to EM_QUEUE_PRIO_UNDEF by em_queue_param_init(), but the user needs to change it to a valid priority, or EM_QUEUE_PRIO_UNDEF if not relevant for the queue type.

Definition at line 727 of file event_machine_queue.h.

◆ queue

em_queue_t em_queue_param_t::queue

Requested queue handle for static queues, use EM_QUEUE_UNDEF for dynamic queues.

Dynamic queue: use EM_QUEUE_UNDEF and EM will allocate a queue handle for the new queue (similar to em_queue_create/_ag()). Static queue: use a valid free static queue handle (derived e.g. with em_queue_static_handle()) for the new queue (similar to em_queue_create_static/_ag()). Set to EM_QUEUE_UNDEF by em_queue_param_init(), which means a dynamic queue will be created unless changed by the user.

Definition at line 712 of file event_machine_queue.h.

◆ queue_group

em_queue_group_t em_queue_param_t::queue_group

Queue group for this queue, mandatory for certain queue types. Set to EM_QUEUE_GROUP_UNDEF by em_queue_param_init(), but the user needs to change it to a valid queue group, or EM_QUEUE_GROUP_UNDEF if not relevant for the queue type.

Definition at line 735 of file event_machine_queue.h.

◆ type

em_queue_type_t em_queue_param_t::type

Queue type, mandatory. Set to EM_QUEUE_TYPE_UNDEF by em_queue_param_init(), but the user needs to change it to a valid type.

Definition at line 719 of file event_machine_queue.h.

The documentation for this struct was generated from the following file:

event_machine_queue.h

Data Fields