![]() |
![]() |
Generic declarations. More...
Data Structures | |
struct | em_notif_t |
Defines | |
#define | EM_CORE_MASK_SIZE 64 |
#define | EM_EO_NAME_LEN (32) |
#define | EM_EO_UNDEF EM_UNDEF_U32 |
#define | EM_ERROR 0xffffffff |
#define | EM_ERROR_FATAL_MASK (0x80000000u) |
#define | EM_ERROR_IS_FATAL(error) (EM_ERROR_FATAL_MASK & (error)) |
#define | EM_ERROR_SET_FATAL(error) (EM_ERROR_FATAL_MASK | (error)) |
#define | EM_ESCOPE(escope) (EM_ESCOPE_BIT & (escope)) |
#define | EM_ESCOPE_ALLOC (EM_ESCOPE_API_MASK | 0x0401) |
#define | EM_ESCOPE_API(escope) (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_API_MASK) |
#define | EM_ESCOPE_API_MASK (EM_ESCOPE_BIT | (EM_ESCOPE_API_TYPE << 24)) |
#define | EM_ESCOPE_API_TYPE (0xFFu) |
#define | EM_ESCOPE_ATOMIC_PROCESSING_END (EM_ESCOPE_API_MASK | 0x0404) |
#define | EM_ESCOPE_BIT (0x80000000u) |
#define | EM_ESCOPE_CORE_COUNT (EM_ESCOPE_API_MASK | 0x0302) |
#define | EM_ESCOPE_CORE_ID (EM_ESCOPE_API_MASK | 0x0301) |
#define | EM_ESCOPE_EO_ADD_QUEUE (EM_ESCOPE_API_MASK | 0x0204) |
#define | EM_ESCOPE_EO_CREATE (EM_ESCOPE_API_MASK | 0x0201) |
#define | EM_ESCOPE_EO_DELETE (EM_ESCOPE_API_MASK | 0x0202) |
#define | EM_ESCOPE_EO_GET_NAME (EM_ESCOPE_API_MASK | 0x0203) |
#define | EM_ESCOPE_EO_REGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0206) |
#define | EM_ESCOPE_EO_REMOVE_QUEUE (EM_ESCOPE_API_MASK | 0x0205) |
#define | EM_ESCOPE_EO_START (EM_ESCOPE_API_MASK | 0x0208) |
#define | EM_ESCOPE_EO_STOP (EM_ESCOPE_API_MASK | 0x0209) |
#define | EM_ESCOPE_EO_UNREGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0207) |
#define | EM_ESCOPE_ERROR (EM_ESCOPE_API_MASK | 0x0503) |
#define | EM_ESCOPE_FREE (EM_ESCOPE_API_MASK | 0x0402) |
#define | EM_ESCOPE_INTERNAL(escope) (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_INTERNAL_MASK) |
#define | EM_ESCOPE_INTERNAL_MASK (EM_ESCOPE_BIT | (EM_ESCOPE_INTERNAL_TYPE << 24)) |
#define | EM_ESCOPE_INTERNAL_TYPE (0x00u) |
#define | EM_ESCOPE_MASK (0xFF000000) |
#define | EM_ESCOPE_QUEUE_CREATE (EM_ESCOPE_API_MASK | 0x0001) |
#define | EM_ESCOPE_QUEUE_CREATE_STATIC (EM_ESCOPE_API_MASK | 0x0002) |
#define | EM_ESCOPE_QUEUE_DELETE (EM_ESCOPE_API_MASK | 0x0003) |
#define | EM_ESCOPE_QUEUE_DISABLE (EM_ESCOPE_API_MASK | 0x0006) |
#define | EM_ESCOPE_QUEUE_DISABLE_ALL (EM_ESCOPE_API_MASK | 0x0007) |
#define | EM_ESCOPE_QUEUE_ENABLE (EM_ESCOPE_API_MASK | 0x0004) |
#define | EM_ESCOPE_QUEUE_ENABLE_ALL (EM_ESCOPE_API_MASK | 0x0005) |
#define | EM_ESCOPE_QUEUE_GET_CONTEXT (EM_ESCOPE_API_MASK | 0x0009) |
#define | EM_ESCOPE_QUEUE_GET_GROUP (EM_ESCOPE_API_MASK | 0x000D) |
#define | EM_ESCOPE_QUEUE_GET_NAME (EM_ESCOPE_API_MASK | 0x000A) |
#define | EM_ESCOPE_QUEUE_GET_PRIORITY (EM_ESCOPE_API_MASK | 0x000B) |
#define | EM_ESCOPE_QUEUE_GET_TYPE (EM_ESCOPE_API_MASK | 0x000C) |
#define | EM_ESCOPE_QUEUE_GROUP_CREATE (EM_ESCOPE_API_MASK | 0x0101) |
#define | EM_ESCOPE_QUEUE_GROUP_DELETE (EM_ESCOPE_API_MASK | 0x0102) |
#define | EM_ESCOPE_QUEUE_GROUP_FIND (EM_ESCOPE_API_MASK | 0x0104) |
#define | EM_ESCOPE_QUEUE_GROUP_MASK (EM_ESCOPE_API_MASK | 0x0105) |
#define | EM_ESCOPE_QUEUE_GROUP_MODIFY (EM_ESCOPE_API_MASK | 0x0103) |
#define | EM_ESCOPE_QUEUE_SET_CONTEXT (EM_ESCOPE_API_MASK | 0x0008) |
#define | EM_ESCOPE_REGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0501) |
#define | EM_ESCOPE_SEND (EM_ESCOPE_API_MASK | 0x0403) |
#define | EM_ESCOPE_UNREGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0502) |
#define | EM_EVENT_GROUP_MAX_NOTIF (8) |
#define | EM_EVENT_GROUP_UNDEF EM_UNDEF_U32 |
#define | EM_EVENT_UNDEF (0x00000000u) |
#define | EM_MAX_EOS (256) |
#define | EM_MAX_EVENT_GROUPS (1024) |
#define | EM_MAX_QUEUE_GROUPS (16u) |
#define | EM_MAX_QUEUES (TI_EM_QUEUE_SET_NUM * TI_EM_QUEUE_NUM_IN_SET) |
#define | EM_OK 0 |
#define | EM_POOL_DEFAULT (0u) |
#define | EM_QUEUE_GROUP_DEFAULT (1u) |
#define | EM_QUEUE_GROUP_NAME_LEN (8u) |
#define | EM_QUEUE_GROUP_UNDEF EM_UNDEF_U32 |
#define | EM_QUEUE_NAME_LEN (32) |
#define | EM_QUEUE_STATIC_MAX ((TI_EM_QUEUE_SET_NUM * TI_EM_STATIC_QUEUE_NUM_IN_SET) - 1) |
#define | EM_QUEUE_STATIC_MIN (1) |
#define | EM_QUEUE_STATIC_NUM (EM_QUEUE_STATIC_MAX - EM_QUEUE_STATIC_MIN + 1) |
#define | EM_QUEUE_UNDEF EM_UNDEF_U32 |
#define | EM_UNDEF_U16 (0x0000u) |
#define | EM_UNDEF_U32 (0x00000000u) |
#define | EM_UNDEF_U64 (0x0000000000000000u) |
#define | EM_UNDEF_U8 (0x00u) |
#define | PRI_EGRP PRIu32 |
#define | PRI_EO PRIu32 |
#define | PRI_QGRP PRIu32 |
#define | PRI_QUEUE PRIu32 |
Typedefs | |
typedef union em_core_mask_t | em_core_mask_t |
typedef uint32_t | em_eo_t |
typedef em_status_t(* | em_error_handler_t )(em_eo_t eo, em_status_t error, em_escope_t escope, va_list args) |
typedef uint32_t | em_escope_t |
typedef uint32_t | em_event_group_t |
typedef uint32_t | em_event_t |
typedef enum em_event_type_major_e | em_event_type_major_e |
typedef enum em_event_type_sw_minor_e | em_event_type_sw_minor_e |
typedef uint32_t | em_event_type_t |
typedef struct em_notif_t | em_notif_t |
typedef uint32_t | em_pool_id_t |
typedef uint32_t | em_queue_group_t |
typedef enum em_queue_prio_e | em_queue_prio_e |
typedef uint32_t | em_queue_prio_t |
typedef uint32_t | em_queue_t |
typedef enum em_queue_type_e | em_queue_type_e |
typedef uint32_t | em_queue_type_t |
typedef void(* | em_receive_func_t )(void *eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void *q_ctx) |
typedef em_status_t(* | em_start_func_t )(void *eo_ctx, em_eo_t eo) |
typedef em_status_t(* | em_start_local_func_t )(void *eo_ctx, em_eo_t eo) |
typedef enum em_status_e | em_status_e |
typedef uint32_t | em_status_t |
typedef em_status_t(* | em_stop_func_t )(void *eo_ctx, em_eo_t eo) |
typedef em_status_t(* | em_stop_local_func_t )(void *eo_ctx, em_eo_t eo) |
Enumerations | |
enum | em_event_type_major_e |
enum | em_event_type_sw_minor_e |
enum | em_queue_prio_e |
enum | em_queue_type_e |
enum | em_status_e |
Functions | |
em_event_t | em_alloc (size_t size, em_event_type_t type, em_pool_id_t pool_id) |
void | em_atomic_processing_end (void) |
int | em_core_count (void) |
int | em_core_id (void) |
int | em_core_id_get_physical (int core) |
static void | em_core_mask_clr (int core, em_core_mask_t *mask) |
static void | em_core_mask_copy (em_core_mask_t *dest, const em_core_mask_t *src) |
static int | em_core_mask_count (const em_core_mask_t *mask) |
static int | em_core_mask_equal (const em_core_mask_t *mask1, const em_core_mask_t *mask2) |
void | em_core_mask_get_physical (em_core_mask_t *phys, const em_core_mask_t *logic) |
static int | em_core_mask_isset (int core, const em_core_mask_t *mask) |
static int | em_core_mask_iszero (const em_core_mask_t *mask) |
static void | em_core_mask_set (int core, em_core_mask_t *mask) |
static void | em_core_mask_set_count (int count, em_core_mask_t *mask) |
static void | em_core_mask_zero (em_core_mask_t *mask) |
em_status_t | em_eo_add_queue (em_eo_t eo, em_queue_t queue) |
em_eo_t | em_eo_create (const char *name, em_start_func_t start, em_start_local_func_t local_start, em_stop_func_t stop, em_stop_local_func_t local_stop, em_receive_func_t receive, const void *eo_ctx) |
em_status_t | em_eo_delete (em_eo_t eo) |
size_t | em_eo_get_name (em_eo_t eo, char *name, size_t maxlen) |
em_status_t | em_eo_register_error_handler (em_eo_t eo, em_error_handler_t handler) |
em_status_t | em_eo_remove_queue (em_eo_t eo, em_queue_t queue, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_eo_start (em_eo_t eo, em_status_t *result, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_eo_stop (em_eo_t eo, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_eo_unregister_error_handler (em_eo_t eo) |
void | em_error (em_status_t error, em_escope_t escope,...) |
int | em_error_format_string (char *str, size_t size, em_eo_t eo, em_status_t error, em_escope_t escope, va_list args) |
em_status_t | em_event_group_apply (em_event_group_t group, int count, int num_notif, const em_notif_t *notif_tbl) |
em_event_group_t | em_event_group_create (void) |
em_event_group_t | em_event_group_current (void) |
em_status_t | em_event_group_delete (em_event_group_t event_group) |
em_status_t | em_event_group_increment (int count) |
void * | em_event_pointer (const em_event_t event) |
void | em_free (em_event_t event) |
em_event_type_t | em_get_type_major (em_event_type_t type) |
em_event_type_t | em_get_type_minor (em_event_type_t type) |
em_queue_t | em_queue_create (const char *name, em_queue_type_t type, em_queue_prio_t prio, em_queue_group_t group) |
em_status_t | em_queue_create_static (const char *name, em_queue_type_t type, em_queue_prio_t prio, em_queue_group_t group, em_queue_t queue) |
em_status_t | em_queue_delete (em_queue_t queue) |
em_status_t | em_queue_disable (em_queue_t queue, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_queue_disable_all (em_eo_t eo, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_queue_enable (em_queue_t queue) |
em_status_t | em_queue_enable_all (em_eo_t eo) |
void * | em_queue_get_context (em_queue_t queue) |
em_queue_group_t | em_queue_get_group (em_queue_t queue) |
size_t | em_queue_get_name (em_queue_t queue, char *name, size_t maxlen) |
em_queue_prio_t | em_queue_get_priority (em_queue_t queue) |
em_queue_type_t | em_queue_get_type (em_queue_t queue) |
em_queue_group_t | em_queue_group_create (const char *name, const em_core_mask_t *mask, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_queue_group_delete (em_queue_group_t group, int num_notif, const em_notif_t *notif_tbl) |
em_queue_group_t | em_queue_group_find (const char *name) |
em_status_t | em_queue_group_mask (em_queue_group_t group, em_core_mask_t *mask) |
em_status_t | em_queue_group_modify (em_queue_group_t group, const em_core_mask_t *new_mask, int num_notif, const em_notif_t *notif_tbl) |
em_status_t | em_queue_set_context (em_queue_t queue, const void *context) |
em_status_t | em_register_error_handler (em_error_handler_t handler) |
em_status_t | em_send (em_event_t event, em_queue_t queue) |
em_status_t | em_send_group (em_event_t event, em_queue_t queue, em_event_group_t group) |
em_status_t | em_unregister_error_handler (void) |
Generic declarations.
#define EM_CORE_MASK_SIZE 64 |
Size of the core mask in bits
#define EM_EO_NAME_LEN (32) |
Max EO name string lenght.
#define EM_EO_UNDEF EM_UNDEF_U32 |
Invalid EO id
#define EM_ERROR 0xffffffff |
Operation not successful
#define EM_ERROR_FATAL_MASK (0x80000000u) |
Fatal error mask
#define EM_ERROR_IS_FATAL | ( | error | ) | (EM_ERROR_FATAL_MASK & (error)) |
Test if error is fatal
#define EM_ERROR_SET_FATAL | ( | error | ) | (EM_ERROR_FATAL_MASK | (error)) |
Set a fatal error code
#define EM_ESCOPE | ( | escope | ) | (EM_ESCOPE_BIT & (escope)) |
Test if the error scope identifies an EM function (API or other internal)
#define EM_ESCOPE_ALLOC (EM_ESCOPE_API_MASK | 0x0401) |
Error scope for the em_alloc API.
#define EM_ESCOPE_API | ( | escope | ) | (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_API_MASK) |
Test if the error scope identifies an API function
#define EM_ESCOPE_API_MASK (EM_ESCOPE_BIT | (EM_ESCOPE_API_TYPE << 24)) |
EM API functions error scope mask
#define EM_ESCOPE_API_TYPE (0xFFu) |
EM API functions error scope type
#define EM_ESCOPE_ATOMIC_PROCESSING_END (EM_ESCOPE_API_MASK | 0x0404) |
Error scope for the em_atomic_processing_end API.
#define EM_ESCOPE_BIT (0x80000000u) |
All EM internal error scopes should have bit 31 set NOTE: High bit is RESERVED for EM internal escopes and should not be used by the application.
#define EM_ESCOPE_CORE_COUNT (EM_ESCOPE_API_MASK | 0x0302) |
Error scope for the em_core_count API.
#define EM_ESCOPE_CORE_ID (EM_ESCOPE_API_MASK | 0x0301) |
Error scope for the em_core_id API.
#define EM_ESCOPE_EO_ADD_QUEUE (EM_ESCOPE_API_MASK | 0x0204) |
Error scope for the em_eo_add_queue API.
#define EM_ESCOPE_EO_CREATE (EM_ESCOPE_API_MASK | 0x0201) |
Error scope for the em_eo_create API.
#define EM_ESCOPE_EO_DELETE (EM_ESCOPE_API_MASK | 0x0202) |
Error scope for the em_eo_delete API.
#define EM_ESCOPE_EO_GET_NAME (EM_ESCOPE_API_MASK | 0x0203) |
Error scope for the em_eo_get_name API.
#define EM_ESCOPE_EO_REGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0206) |
Error scope for the em_eo_register_error_handler API.
#define EM_ESCOPE_EO_REMOVE_QUEUE (EM_ESCOPE_API_MASK | 0x0205) |
Error scope for the em_eo_remove_queue API.
#define EM_ESCOPE_EO_START (EM_ESCOPE_API_MASK | 0x0208) |
Error scope for the em_eo_start API.
#define EM_ESCOPE_EO_STOP (EM_ESCOPE_API_MASK | 0x0209) |
Error scope for the em_eo_stop API.
#define EM_ESCOPE_EO_UNREGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0207) |
Error scope for the em_eo_unregister_error_handler API.
#define EM_ESCOPE_ERROR (EM_ESCOPE_API_MASK | 0x0503) |
Error scope for the em_error API.
#define EM_ESCOPE_FREE (EM_ESCOPE_API_MASK | 0x0402) |
Error scope for the em_free API.
#define EM_ESCOPE_INTERNAL | ( | escope | ) | (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_INTERNAL_MASK) |
Test if the error scope identifies an EM Internal function
#define EM_ESCOPE_INTERNAL_MASK (EM_ESCOPE_BIT | (EM_ESCOPE_INTERNAL_TYPE << 24)) |
EM internal error scope type
#define EM_ESCOPE_INTERNAL_TYPE (0x00u) |
EM internal error scope mask
#define EM_ESCOPE_MASK (0xFF000000) |
Mask selects the high byte of the 32-bit escope
#define EM_ESCOPE_QUEUE_CREATE (EM_ESCOPE_API_MASK | 0x0001) |
Error scope for the em_queue_create API.
#define EM_ESCOPE_QUEUE_CREATE_STATIC (EM_ESCOPE_API_MASK | 0x0002) |
Error scope for the em_queue_create_static API.
#define EM_ESCOPE_QUEUE_DELETE (EM_ESCOPE_API_MASK | 0x0003) |
Error scope for the em_queue_delete API.
#define EM_ESCOPE_QUEUE_DISABLE (EM_ESCOPE_API_MASK | 0x0006) |
Error scope for the em_queue_disable API.
#define EM_ESCOPE_QUEUE_DISABLE_ALL (EM_ESCOPE_API_MASK | 0x0007) |
Error scope for the em_queue_disable_all API.
#define EM_ESCOPE_QUEUE_ENABLE (EM_ESCOPE_API_MASK | 0x0004) |
Error scope for the em_queue_enable API.
#define EM_ESCOPE_QUEUE_ENABLE_ALL (EM_ESCOPE_API_MASK | 0x0005) |
Error scope for the em_queue_enable_all API.
#define EM_ESCOPE_QUEUE_GET_CONTEXT (EM_ESCOPE_API_MASK | 0x0009) |
Error scope for the em_queue_get_context API.
#define EM_ESCOPE_QUEUE_GET_GROUP (EM_ESCOPE_API_MASK | 0x000D) |
Error scope for the em_queue_group_create API.
#define EM_ESCOPE_QUEUE_GET_NAME (EM_ESCOPE_API_MASK | 0x000A) |
Error scope for the em_queue_get_name API.
#define EM_ESCOPE_QUEUE_GET_PRIORITY (EM_ESCOPE_API_MASK | 0x000B) |
Error scope for the em_queue_get_priority API.
#define EM_ESCOPE_QUEUE_GET_TYPE (EM_ESCOPE_API_MASK | 0x000C) |
Error scope for the em_queue_get_type API.
#define EM_ESCOPE_QUEUE_GROUP_CREATE (EM_ESCOPE_API_MASK | 0x0101) |
Error scope for the em_queue_group_create API.
#define EM_ESCOPE_QUEUE_GROUP_DELETE (EM_ESCOPE_API_MASK | 0x0102) |
Error scope for the em_queue_group_delete API.
#define EM_ESCOPE_QUEUE_GROUP_FIND (EM_ESCOPE_API_MASK | 0x0104) |
Error scope for the em_queue_group_find API.
#define EM_ESCOPE_QUEUE_GROUP_MASK (EM_ESCOPE_API_MASK | 0x0105) |
Error scope for the em_queue_group_mask API.
#define EM_ESCOPE_QUEUE_GROUP_MODIFY (EM_ESCOPE_API_MASK | 0x0103) |
Error scope for the em_queue_group_modify API.
#define EM_ESCOPE_QUEUE_SET_CONTEXT (EM_ESCOPE_API_MASK | 0x0008) |
Error scope for the em_queue_set_context API.
#define EM_ESCOPE_REGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0501) |
Error scope for the em_register_error_handler API.
#define EM_ESCOPE_SEND (EM_ESCOPE_API_MASK | 0x0403) |
Error scope for the em_send API.
#define EM_ESCOPE_UNREGISTER_ERROR_HANDLER (EM_ESCOPE_API_MASK | 0x0502) |
Error scope for the em_unregister_error_handler API.
#define EM_EVENT_GROUP_MAX_NOTIF (8) |
Maximum number of event notifications supported by one event group.
#define EM_EVENT_GROUP_UNDEF EM_UNDEF_U32 |
Invalid event group id
#define EM_EVENT_UNDEF (0x00000000u) |
Undefined event
#define EM_MAX_EOS (256) |
Maximum number of execution objects supported by the event machine. EM_MAX_EOS <= TI_EM_EO_NUM_MAX.
#define EM_MAX_EVENT_GROUPS (1024) |
Maximum number of event groups supported by the event machine. EM_MAX_EVENT_GROUPS <= TI_EM_EVENT_GROUP_NUM_MAX.
#define EM_MAX_QUEUE_GROUPS (16u) |
Maximum number of queue groups supported by the event machine.
#define EM_MAX_QUEUES (TI_EM_QUEUE_SET_NUM * TI_EM_QUEUE_NUM_IN_SET) |
Maximum number of queues supported by the event machine.
#define EM_OK 0 |
Operation successful
#define EM_POOL_DEFAULT (0u) |
Define default memory pool
#define EM_QUEUE_GROUP_DEFAULT (1u) |
Default queue group for EM
#define EM_QUEUE_GROUP_NAME_LEN (8u) |
Max queue group name string lenght.
#define EM_QUEUE_GROUP_UNDEF EM_UNDEF_U32 |
Invalid queue group id
#define EM_QUEUE_NAME_LEN (32) |
Max queue name string length.
#define EM_QUEUE_STATIC_MAX ((TI_EM_QUEUE_SET_NUM * TI_EM_STATIC_QUEUE_NUM_IN_SET) - 1) |
Static queues: maximal value
#define EM_QUEUE_STATIC_MIN (1) |
Static queues: minimal value
#define EM_QUEUE_STATIC_NUM (EM_QUEUE_STATIC_MAX - EM_QUEUE_STATIC_MIN + 1) |
Static queues: number of status queues
#define EM_QUEUE_UNDEF EM_UNDEF_U32 |
Invalid queue
#define EM_UNDEF_U16 (0x0000u) |
Invalid identifier (16-bit)
#define EM_UNDEF_U32 (0x00000000u) |
Invalid identifier (32-bit)
#define EM_UNDEF_U64 (0x0000000000000000u) |
Invalid identifier (64-bit)
#define EM_UNDEF_U8 (0x00u) |
Invalid identifier (8-bit)
#define PRI_EGRP PRIu32 |
em_event_group_t printf format
#define PRI_EO PRIu32 |
em_eo_t printf format
#define PRI_QGRP PRIu32 |
em_queue_group_t printf format
#define PRI_QUEUE PRIu32 |
em_queue_t printf format
typedef union em_core_mask_t em_core_mask_t |
Type for queue group core mask. Each bit represents one core, core 0 is the lsb (1 << em_core_id()) Note, that EM will enumerate the core identifiers to always start from 0 and be contiguous meaning the core numbers are not necessarily physical. This type can handle up to 64 cores.
typedef uint32_t em_eo_t |
Execution Object identifier
typedef em_status_t(* em_error_handler_t)(em_eo_t eo, em_status_t error, em_escope_t escope, va_list args) |
Error handler.
Error handler maybe called after EM notices an error or user have called em_error().
User can register EO specific and/or EM global error handlers. When an error is noticed, EM calls EO specific error handler, if registered. If there's no EO specific handler registered (for the EO) or the error is noticed outside of an EO context, EM calls the global error handler (if registered). If no error handlers are found, EM just returns an error code depending on the API function.
Error handler is called with the original error code from the API call or em_error(). Error scope identifies the source of the error and how the error code and variable arguments should be interpreted (number of arguments and types).
eo | Execution object id |
error | The error code |
escope | Error scope. Identifies the scope for interpreting the error code and variable arguments. |
args | Variable number and type of arguments |
typedef uint32_t em_escope_t |
Error scope.
Identifies the error scope for interpreting error codes and variable arguments.
typedef uint32_t em_event_group_t |
Event group id. This is used for fork-join event handling.
typedef uint32_t em_event_t |
Event type
In Event Machine application processing is driven by events. An event describes a piece of work. Structure of an event is implementation and event type specific. It may be a directly accessible buffer of memory, a descriptor containing a list of buffer pointers, a descriptor of a packet buffer, etc.
Applications use event type to interpret the event structure.
Since em_event_t may not carry a direct pointer value to the event structure, em_event_pointer() must be used to translate an event to an event structure pointer (for maintaining portability).
typedef enum em_event_type_major_e em_event_type_major_e |
The structure describes the major event types
typedef enum em_event_type_sw_minor_e em_event_type_sw_minor_e |
The structure describes the Minor event types for the major EM_EVENT_TYPE_SW type
typedef uint32_t em_event_type_t |
Event type. This is given to application for each received event and also needed for event allocation. It's an integer, but split into major and minor part. major-field categorizes the event and minor is more detailed system specific description. Major-part will not change by HW, but minor can be HW/SW platform specific and thus could be split into more sub-fields as needed. Application should use the access functions for reading major and minor part.
The only event type with defined content is EM_EVENT_TYPE_SW with minor type 0, which needs to be portable (direct pointer to data).
typedef struct em_notif_t em_notif_t |
Notification structure allows user to define a notification event and destination queue pair. EM will notify user by sending the event into the queue.
typedef uint32_t em_pool_id_t |
Memory pool id.
Defines memory pool in em_alloc(). Default pool id is defined by EM_POOL_DEFAULT.
typedef uint32_t em_queue_group_t |
Queue group identifier
Each queue belongs to one queue group, that defines a core mask for scheduling events, i.e. define which cores participate in the load balancing. Group can also allow only a single core for no load balancing.
Groups needs to be created as needed. One default group (EM_QUEUE_GROUP_DEFAULT) always exists, and that allows scheduling to all the cores running this execution binary instance.
typedef enum em_queue_prio_e em_queue_prio_e |
The structure describes the portable queue priorities
typedef uint32_t em_queue_prio_t |
Queue priority class
Queue priority defines a system dependent QoS class, not just an absolute priority. EM gives freedom to implement the actual scheduling disciplines and the corresponding numeric values as needed, i.e. the actual values are system dependent and thus not portable, but the 5 pre-defined enums (em_queue_prio_e) are always valid. Application platform or middleware needs to define and distribute the other available values.
typedef uint32_t em_queue_t |
Queue identifier
typedef enum em_queue_type_e em_queue_type_e |
The structure describes the queue types
typedef uint32_t em_queue_type_t |
typedef void(* em_receive_func_t)(void *eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void *q_ctx) |
Receive event
Application receives events through the EO receive function. It implements main part of the application logic. EM calls the receive function when it has dequeued an event from one of the EO's queues. Application processes the event and returns immediately (in run-to-completion fashion).
On multicore systems several events (from the same or different queues) may be dequeued in parallel and thus same receive function may be executed concurrently on several cores. Parallel execution may be limited by queue group setup or using queues with atomic scheduling mode.
EO and queue context pointers are user defined (in EO and queue creation time) and may be used any way needed. For example, EO context may be used to store global EO state information, which is common to all queues and events. In addition, queue context may be used to store queue (or user data flow) specific state data. EM never touches the data, just passes the pointers.
Event (handle) must be converted to an event structure pointer with em_event_pointer(). Event type specifies the event structure, which is implementation or application specific. Queue id specifies the queue which the event was dequeued from.
eo_ctx | EO context data. The pointer is passed in em_eo_create(), EM does not touch the data. |
event | Event handle |
type | Event type |
queue | Queue from which this event came from |
q_ctx | Queue context data. The pointer is passed in em_queue_set_context(), EM does not touch the data. |
typedef em_status_t(* em_start_func_t)(void *eo_ctx, em_eo_t eo) |
Execution object start, global.
If load balancing/several cores share the EO, this function is called once on one core only (any). Purpose of this global start is to provide a placeholder for first level initialization, like allocating memory and initializing shared data. After this global start returns, the core local version (if defined), is called (see em_start_local_func_t below). If there is no core local start, then event dispatching is immediately enabled.
If Execution object does not return EM_OK, the system will not call the core local init and will not enable event dispatching.
This function should never be called directly from the application, but using the, which maintains state information!
eo_ctx | Execution object internal state/instance data |
eo | Execution object id |
typedef em_status_t(* em_start_local_func_t)(void *eo_ctx, em_eo_t eo) |
Execution object start, core local.
This is similar to the global start above, but this one is called after the global start has completed and is called on all cores.
Purpose of this optional local start is to work as a placeholder for core local initialization, e.g. allocating core local memory for example. The global start is only called on one core. The use of local start is optional. Note, that application should never directly call this function, this will be called via em_eo_start().
If this does not return EM_OK on all involved cores, the event dispatching is not enabled.
eo_ctx | Execution object internal state/instance data |
eo | Execution object id |
typedef enum em_status_e em_status_e |
The structure lists the error codes
typedef uint32_t em_status_t |
Error/Status code. EM_OK (0) is the general code for success, other values describe failed operation.
typedef em_status_t(* em_stop_func_t)(void *eo_ctx, em_eo_t eo) |
Execution object stop, global.
If load balancing/several cores share the EO, this function is called once on one core (any) after the (optional) core local stop return on all cores. System disables event dispatching before calling this and also makes sure this does not get called before all cores have been notified the stop condition for this EO (can't dispatch new events) event if there is no core local stop defined. Return value is only for logging purposes, EM does not use it currently.
Note, that application should never directly call this stop function, but use the em_eo_stop() instead, which maintains state information and guarantees synchronized operation.
eo_ctx | Execution object internal state data |
eo | Execution object id |
typedef em_status_t(* em_stop_local_func_t)(void *eo_ctx, em_eo_t eo) |
Execution object stop, core local.
If load balancing/several cores share the EO, this function is called once on each core before the global stop (reverse order of start). System disables event dispatching before calling this and also makes sure this does not get called before the core has been notified the stop condition for this EO (won't dispatch new events) Return value is only for logging purposes, EM does not use it currently.
Note, that application should never directly call this stop function, em_eo_stop() will trigger this.
eo_ctx | Execution object internal state data |
eo | Execution object id |
The structure describes the Minor event types for the major EM_EVENT_TYPE_SW type
enum em_queue_prio_e |
enum em_queue_type_e |
The structure describes the queue types
enum em_status_e |
The structure lists the error codes
em_event_t em_alloc | ( | size_t | size, |
em_event_type_t | type, | ||
em_pool_id_t | pool_id | ||
) |
Allocate an event.
Memory address of the allocated event is system specific and can depend on given pool id, event size and type. Returned event (handle) may refer to a memory buffer or a HW specific descriptor, i.e. the event structure is system specific.
Use em_event_pointer() to convert an event (handle) to a pointer to the event structure.
EM_EVENT_TYPE_SW with minor type 0 is reserved for direct portability. It is always guaranteed to return a 64-bit aligned contiguous data buffer, that can directly be used by the application up to the given size (no HW specific descriptors etc are visible).
EM_POOL_DEFAULT can be used as pool id if there's no need to use any specific memory pool.
Additionally it is guaranteed, that two separate buffers never share a cache line to avoid false sharing.
size | Event size in octets |
type | Event type to allocate |
pool_id | Event pool id |
void em_atomic_processing_end | ( | void | ) |
Release atomic processing context.
When an event was received from an atomic queue, the function can be used to release the atomic context before receive function return. After the call, scheduler is allowed to schedule another event from the same queue to another core. This increases parallelism and may improve performance - however the exclusive processing and ordering (!) might be lost after the call.
Can only be called from within the event receive function!
The call is ignored, if current event was not received from an atomic queue.
Pseudo-code example:
receive_func(void* eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void* q_ctx); { if(is_my_atomic_queue(q_ctx)) { update_sequence_number(event); // this needs to be done atomically em_atomic_processing_end(); ... // do other processing (potentially) in parallel } }
int em_core_count | ( | void | ) |
The number of cores running within the same EM instance (sharing the EM state).
int em_core_id | ( | void | ) |
Logical core id.
Returns the logical id of the current core. EM enumerates cores (or HW threads) to always start from 0 and be contiguous, i.e. valid core identifiers are 0...em_core_count()-1
int em_core_id_get_physical | ( | int | core | ) |
Converts a logical core id to a physical core id
Mainly needed when interfacing HW specific APIs
core | logical (Event Machine) core id |
static void em_core_mask_clr | ( | int | core, |
em_core_mask_t * | mask | ||
) | [inline, static] |
Clear a bit in the mask.
core | Core id |
mask | Core mask |
static void em_core_mask_copy | ( | em_core_mask_t * | dest, |
const em_core_mask_t * | src | ||
) | [inline, static] |
Copy core mask
dest | Destination core mask |
src | Source core mask |
static int em_core_mask_count | ( | const em_core_mask_t * | mask | ) | [inline, static] |
Count the number of bits set in the mask.
mask | Core mask |
static int em_core_mask_equal | ( | const em_core_mask_t * | mask1, |
const em_core_mask_t * | mask2 | ||
) | [inline, static] |
Test if two masks are equal
mask1 | First core mask |
mask2 | Second core mask |
void em_core_mask_get_physical | ( | em_core_mask_t * | phys, |
const em_core_mask_t * | logic | ||
) |
Converts a logical core mask to a physical core mask
Mainly needed when interfacing HW specific APIs
phys | Core mask of physical core ids |
logic | Core mask of logical (Event Machine) core ids |
static int em_core_mask_isset | ( | int | core, |
const em_core_mask_t * | mask | ||
) | [inline, static] |
Test if a bit is set in the mask.
core | Core id |
mask | Core mask |
static int em_core_mask_iszero | ( | const em_core_mask_t * | mask | ) | [inline, static] |
Test if the mask is all zero.
mask | Core mask |
static void em_core_mask_set | ( | int | core, |
em_core_mask_t * | mask | ||
) | [inline, static] |
Set a bit in the mask.
core | Core id |
mask | Core mask |
static void em_core_mask_set_count | ( | int | count, |
em_core_mask_t * | mask | ||
) | [inline, static] |
Set a range (0...count-1) of bits in the mask.
count | Number of bits to set |
mask | Core mask |
static void em_core_mask_zero | ( | em_core_mask_t * | mask | ) | [inline, static] |
Zero the whole mask.
mask | Core mask |
em_status_t em_eo_add_queue | ( | em_eo_t | eo, |
em_queue_t | queue | ||
) |
Add a queue to an EO.
Note, that this does not enable the queue. Although queues added in (or before) the start function will be enabled automatically.
eo | EO id |
queue | Queue id |
em_eo_t em_eo_create | ( | const char * | name, |
em_start_func_t | start, | ||
em_start_local_func_t | local_start, | ||
em_stop_func_t | stop, | ||
em_stop_local_func_t | local_stop, | ||
em_receive_func_t | receive, | ||
const void * | eo_ctx | ||
) |
Create Execution Object (EO).
This will allocate identifier and initialize internal data for a new EO. It is left in a non-active state, i.e. no events are dispatched before em_eo_start() has called. Start, stop and receive callback function pointers are mandatory parameters.
The name given is copied to EO internal data and can be used e.g. for debugging. The maximum length stored is EM_EO_NAME_LEN.
name | Name of the EO (NULL if no name) |
start | Start function |
local_start | Core local start function (NULL if no local start) |
stop | Stop function |
local_stop | Core local stop function (NULL if no local stop) |
receive | Receive function |
eo_ctx | User defined EO context data, EM just passes the pointer (NULL if not context) |
em_status_t em_eo_delete | ( | em_eo_t | eo | ) |
Delete Execution Object (EO).
This will immediately delete the given EO and free the identifier.
NOTE, that EO can only be deleted after it has been stopped using em_eo_stop(), otherwise another core might still access the EO data! Deletion will fail, if the EO is not stopped.
This will delete all possibly remaining queues.
eo | EO id to delete |
size_t em_eo_get_name | ( | em_eo_t | eo, |
char * | name, | ||
size_t | maxlen | ||
) |
Returns the name given to the EO when it was created.
A copy of the name string (up to 'maxlen' characters) is written to the user buffer 'name'. String is always null terminated even if the given buffer length is less than the name length.
If the EO has no name, function returns 0 and writes empty string.
This is only for debugging purposes.
eo | EO id |
name | Destination buffer |
maxlen | Maximum length (including the terminating '0') |
em_status_t em_eo_register_error_handler | ( | em_eo_t | eo, |
em_error_handler_t | handler | ||
) |
Register EO specific error handler.
The EO specific error handler is called if error is noticed or em_error() is called in the context of the EO. Note, the function will override any previously registered error hanler.
eo | EO id |
handler | New error handler. |
em_status_t em_eo_remove_queue | ( | em_eo_t | eo, |
em_queue_t | queue, | ||
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Removes a queue from an EO.
Function disables scheduling of the queue and removes the queue from the EO. The operation is asynchronous, to quarantee that all cores have completed processing of events from the queue (i.e. there's no cores in middle of the receive function) before removing it.
If the caller needs to know when the context deletion actually occurred, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the removal has completed. If such notification is not needed, use 0 as num_notif.
If the queue to be removed is still enabled, it will first be disabled.
eo | EO id |
queue | Queue id to remove |
num_notif | How many notification events given, 0 for no notification |
notif_tbl | Array of pairs of event and queue identifiers |
em_status_t em_eo_start | ( | em_eo_t | eo, |
em_status_t * | result, | ||
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Start Execution Object (EO).
Calls global EO start function. If that returns EM_OK, an internal event to trigger local start is sent to all cores belonging to the queue group of this EO. If the global start function does not return EM_OK the local start is not called and event dispatching is not enabled for this EO.
If the caller needs to know when the EO start was actually completed on all cores, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the start is completed on all cores. If local start does not exist the notification(s) are sent as the global start returns. If such notification is not needed, use 0 as num_notif.
eo | EO id |
result | Optional pointer to em_status_t, which gets updated to the return value of the actual EO global start function |
num_notif | If not 0, defines the number of events to send as all cores have returned from the start function (in notif_tbl). |
notif_tbl | Array of em_notif_t, the optional notification events (data copied) |
em_status_t em_eo_stop | ( | em_eo_t | eo, |
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Stop Execution Object (EO).
Disables event dispatch from all related queues, calls core local stop on all cores and finally calls the global stop function of the EO, when all cores have returned from the (optional) core local stop. Call to the global EO stop is asynchronous and only done, when all cores have completed processing of the receive function and/or core local stop. This guarantees no core is accessing EO data during EO global stop function.
This function returns immediately.
If the caller needs to know when the EO stop was actually completed, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the stop actually completes. If such notification is not needed, use 0 as num_notif.
eo | EO id |
num_notif | How many notification events given, 0 for no notification |
notif_tbl | Array of pairs of event and queue identifiers |
em_status_t em_eo_unregister_error_handler | ( | em_eo_t | eo | ) |
Unregister EO specific error handler.
Removes previously registered EO specific error handler.
eo | EO id |
void em_error | ( | em_status_t | error, |
em_escope_t | escope, | ||
... | |||
) |
Report an error.
Reported errors are handled by the appropriate (EO specific or the global) error handler.
Depending on the error/scope/implementation, the function call may not return.
error | Error code |
escope | Error scope. Identifies the scope for interpreting the error code and variable arguments. |
... | Variable number and type of arguments |
int em_error_format_string | ( | char * | str, |
size_t | size, | ||
em_eo_t | eo, | ||
em_status_t | error, | ||
em_escope_t | escope, | ||
va_list | args | ||
) |
Format error string
Creates an implementation dependent error report string from EM internal errors.
str | Output string pointer |
size | Maximum string lenght in characters |
eo | EO id |
error | Error code (EM internal) |
escope | Error scope (EM internal) |
args | Variable arguments |
em_status_t em_event_group_apply | ( | em_event_group_t | group, |
int | count, | ||
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Apply event group configuration.
The function sets (or resets) the event count and notification parameters for the event group. After it returns events sent to the group are counted against the (updated) count. Notification events are sent when all (counted) events have been processed. A new apply call is needed to reset the event group (counting).
group | Group id |
count | Number of events in the group |
num_notif | Number of noticifation events to send |
notif_tbl | Table of notifications (events and target queues) |
em_event_group_t em_event_group_create | ( | void | ) |
Create new event group id for fork-join.
em_event_group_t em_event_group_current | ( | void | ) |
Current event group
Returns the event group of the currently received event or EM_EVENT_GROUP_UNDEF if the current event does not belong into any event group. Current group is needed when sending new events into the group.
em_status_t em_event_group_delete | ( | em_event_group_t | event_group | ) |
Delete (unallocate) an event group id
An event group must not be deleted before it has been completed (notifications sent) or canceled.
event_group | Event group to delete |
em_status_t em_event_group_increment | ( | int | count | ) |
Increment event group count
Increments event count of the current event group. Enables sending new events into the current group. Must be called before sending. Note that event count cannot be decremented.
count | Number of events to add in the group |
void* em_event_pointer | ( | const em_event_t | event | ) |
Get pointer to event structure
Returns pointer to the event structure or NULL. Event structure is implementation and event type specific. It may be a directly accessible buffer of memory, a descriptor containing a list of buffer pointers, a descriptor of a packet buffer, etc.
event | Event from receive/alloc |
void em_free | ( | em_event_t | event | ) |
Free an event.
It is assumed the implementation can detect from which memory area/pool the event was originally allocated from.
Free transfers the ownership of the event to the system and application must not touch the event (or related memory buffers) after calling it.
Application must only free events it owns. For example, sender must not free an event after sending it.
event | Event to be freed |
em_event_type_t em_get_type_major | ( | em_event_type_t | type | ) |
Get major event type.
Event type includes major and minor part. This function returns the major part. It can be compared against enumeration em_event_type_major_e.
type | Event type |
em_event_type_t em_get_type_minor | ( | em_event_type_t | type | ) |
Get minor event type.
Event type includes major and minor part. This function returns the minor part. It can be compared against the enumeration specified by the major part.
EM_EVENT_TYPE_SW_DEFAULT is reserved for (SW) events that are generic and directly accessible buffers of memory.
type | Event type |
em_queue_t em_queue_create | ( | const char * | name, |
em_queue_type_t | type, | ||
em_queue_prio_t | prio, | ||
em_queue_group_t | group | ||
) |
Create a new queue with a dynamic queue id.
The given name string is copied to EM internal data structure. The maximum string length is EM_QUEUE_NAME_LEN.
name | Queue name for debugging purposes (optional, NULL ok) |
type | Queue scheduling type |
prio | Queue priority |
group | Queue group for this queue |
em_status_t em_queue_create_static | ( | const char * | name, |
em_queue_type_t | type, | ||
em_queue_prio_t | prio, | ||
em_queue_group_t | group, | ||
em_queue_t | queue | ||
) |
Create a new queue with a static queue id.
Note, that system may have limited amount of static identifiers, so unless really needed use dynamic queues instead. The range of static identifiers is system dependent, but macros EM_QUEUE_STATIC_MIN and EM_QUEUE_STATIC_MAX can be used to abstract, i.e. use EM_QUEUE_STATIC_MIN+x for the application.
The given name string is copied to EM internal data structure. The maximum string length is EM_QUEUE_NAME_LEN.
name | Queue name for debugging purposes (optional, NULL ok) |
type | Queue scheduling type |
prio | Queue priority |
group | Queue group for this queue |
queue | Requested queue id from the static range |
em_status_t em_queue_delete | ( | em_queue_t | queue | ) |
Delete a queue.
Unallocates the queue id. NOTE: this is an immediate deletion and can *only* be done after the queue has been removed from scheduling using em_eo_remove_queue() !
queue | Queue id to delete |
em_status_t em_queue_disable | ( | em_queue_t | queue, |
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Disable scheduling for the queue.
Note, that this might be an asynchronous operation and actually complete later as other cores may still be handling existing events. If application needs to know exactly when all processing is completed, it can use the notification arguments - the given notification(s) are sent after all cores have completed.
Implicit disable is done for all queues, that are mapped to an EO when it's stop-function is called (via em_eo_stop()).
All events sent to a non-enabled queue may get discarded or held depending on the system. Queue enable/disable is not meant to be used for additional scheduling nor used frequently. Main purpose is to synchronize startup or recovery actions.
queue | Queue to disable |
num_notif | Number of entries in notif_tbl, use 0 for no notification |
notif_tbl | Notification events to send |
em_status_t em_queue_disable_all | ( | em_eo_t | eo, |
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Disable scheduling for all the EO's queues.
Otherwise identical to em_queue_disable().
eo | EO id |
num_notif | Number of entries in notif_tbl, use 0 for no notification |
notif_tbl | Notification events to send |
em_status_t em_queue_enable | ( | em_queue_t | queue | ) |
Enable event scheduling for the queue.
All events sent to a non-enabled queue may get discarded or held depending on the system. Queue enable/disable is not meant to be used for additional scheduling nor used frequently. Main purpose is to synchronize startup or recovery actions.
queue | Queue to enable |
em_status_t em_queue_enable_all | ( | em_eo_t | eo | ) |
Enable event scheduling for all the EO's queues.
Otherwise identical to em_queue_enable().
eo | EO id |
void* em_queue_get_context | ( | em_queue_t | queue | ) |
Get queue specific (application) context.
Returns the value application has earlier set with em_queue_set_context().
queue | Queue which context is requested |
em_queue_group_t em_queue_get_group | ( | em_queue_t | queue | ) |
Get queue's queue group
queue | Queue identifier |
size_t em_queue_get_name | ( | em_queue_t | queue, |
char * | name, | ||
size_t | maxlen | ||
) |
Get queue name.
Returns the name given to a queue when it was created. A copy of the queue name string (up to 'maxlen' characters) is written to the user given buffer. String is always null terminated even if the given buffer length is less than the name length.
If the queue has no name, function returns 0 and writes empty string.
This is only for debugging purposes.
queue | Queue id |
name | Destination buffer |
maxlen | Maximum length (including the terminating '0') |
em_queue_prio_t em_queue_get_priority | ( | em_queue_t | queue | ) |
Get queue priority.
queue | Queue identifier |
em_queue_type_t em_queue_get_type | ( | em_queue_t | queue | ) |
Get queue type (scheduling mode).
queue | Queue identifier |
em_queue_group_t em_queue_group_create | ( | const char * | name, |
const em_core_mask_t * | mask, | ||
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Create a new queue group to control queue to core mapping.
Allocates a new queue group identifier with a given core mask. The group name can have max EM_QUEUE_GROUP_NAME_LEN characters and must be unique since it's used to identify the group. Cores added to the queue group can be changed later with em_queue_group_modify().
This operation may be asynchronous, i.e. the creation may complete well after this function has returned. Provide notification events, if application cares about the actual completion time. EM will send notifications when the operation has completed.
The core mask is visible through em_queue_group_mask() only after the create operation is complete.
Note, that depending on the system, the operation can also happen one core at a time, so an intermediate mask may be active momentarily.
Only manipulate the core mask with the access macros defined in event_machine_core_mask.h as the implementation underneath may change.
EM has a default group (EM_QUEUE_GROUP_DEFAULT) containing all cores. It's named "default", otherwise naming scheme is system specific.
Note, some systems may have a low number of queue groups available.
name | Queue group name. Unique name for identifying the group. |
mask | Core mask for the queue group |
num_notif | Number of entries in notif_tbl (use 0 for no notification) |
notif_tbl | Array of notifications to send to signal completion of operation |
em_status_t em_queue_group_delete | ( | em_queue_group_t | group, |
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Delete the queue group.
Removes all cores from the queue group and free's the identifier for re-use. All queues in the group must be deleted with em_queue_delete() before deleting the group.
group | Queue group to delete |
num_notif | Number of entries in notif_tbl (use 0 for no notification) |
notif_tbl | Array of notifications to send to signal completion of operation |
em_queue_group_t em_queue_group_find | ( | const char * | name | ) |
Finds queue group by name.
This returns the situation at the moment of the inquiry. If another core is modifying the group at the same time the result may not be up-to-date. Application may need to synchronize group modifications.
name | Name of the queue qroup to find |
em_status_t em_queue_group_mask | ( | em_queue_group_t | group, |
em_core_mask_t * | mask | ||
) |
Get current core mask for a queue group.
This returns the situation at the moment of the inquiry. If another core is modifying the group at the same time the result may not be up-to-date. Application may need to synchronize group modifications.
group | Queue group |
mask | Core mask for the queue group |
em_status_t em_queue_group_modify | ( | em_queue_group_t | group, |
const em_core_mask_t * | new_mask, | ||
int | num_notif, | ||
const em_notif_t * | notif_tbl | ||
) |
Modify core mask of an existing queue group.
The function compares the new core mask to the current mask and changes the queue group to core mapping accordingly.
This operation may be asynchronous, i.e. the change may complete well after this function has returned. Provide notification events, if application cares about the actual completion time. EM will send notifications when the operation has completed.
The new core mask is visible through em_queue_group_mask() only after the modify operation is complete.
Note, that depending on the system, the change can also happen one core at a time, so an intermediate mask may be active momentarily.
Only manipulate core mask with the access macros defined in event_machine_core_mask.h as the implementation underneath may change.
group | Queue group to modify |
new_mask | New core mask |
num_notif | Number of entries in notif_tbl (use 0 for no notification) |
notif_tbl | Array of notifications to send |
em_status_t em_queue_set_context | ( | em_queue_t | queue, |
const void * | context | ||
) |
Set queue specific (application) context.
This is just a single pointer associated with a queue. Application can use it to access some context data quickly (without a lookup). The context is given as argument for the receive function. EM does not use the value, it just passes it.
queue | Queue to which associate the context |
context | Context pointer |
em_status_t em_register_error_handler | ( | em_error_handler_t | handler | ) |
Register the global error handler.
The global error handler is called on errors (or em_error() calls) outside of any EO context or if there's no EO specific error handler registered. Note, the function will override any previously registered global error handler.
handler | Error handler. |
em_status_t em_send | ( | em_event_t | event, |
em_queue_t | queue | ||
) |
Send an event to a queue.
Event must have been allocated with em_alloc(), or received via receive-function. Sender must not touch the event after calling em_send as the ownership is moved to system and then to the receiver. If return status is *not* EM_OK, the ownership has not moved and the application is still responsible for the event (e.g. may free it).
EM does not define guaranteed event delivery, i.e. EM_OK return value only means the event was accepted for delivery. It could still be lost during the delivery (e.g. due to disabled/removed queue, queue or system congestion, etc).
event | Event to be sent |
queue | Destination queue |
em_status_t em_send_group | ( | em_event_t | event, |
em_queue_t | queue, | ||
em_event_group_t | group | ||
) |
Send event with group number.
Any valid event and destination queue parameters can be used. Event group id indicates which event group the event belongs to. Event group has to be first created and applied.
event | Event to send |
queue | Destination queue |
group | Event group |
em_status_t em_unregister_error_handler | ( | void | ) |
Unregister the global error handler.
Removes previously registered global error handler.