Snapdragon® Telematics Application Framework (TelAF) Interface Specification
|
#include "le_thread.h"
Go to the source code of this file.
Macros | |
#define | LE_CI_LINKAGE |
#define | LE_COMPONENT_NAME le |
#define | COMPONENT_INIT_PROTOTYPE(name) |
Construct prototype of component init function. More... | |
#define | COMPONENT_INIT_NAME CAT(CAT(_, LE_COMPONENT_NAME), _COMPONENT_INIT) |
Compose component initialization function name. More... | |
#define | COMPONENT_INIT COMPONENT_INIT_PROTOTYPE(COMPONENT_INIT_NAME) |
Compose component initialization function prototype. More... | |
#define | COMPONENT_INIT_ONCE_NAME CAT(COMPONENT_INIT_NAME, _ONCE) |
Compose one-time component initialization function name. More... | |
#define | COMPONENT_INIT_ONCE COMPONENT_INIT_PROTOTYPE(COMPONENT_INIT_ONCE_NAME) |
Compose one-time component initialization function prototype. More... | |
#define | LE_EVENT_INIT_HANDLER COMPONENT_INIT |
Deprecated name for COMPONENT_INIT. More... | |
Typedefs | |
typedef struct le_event_Id * | le_event_Id_t |
typedef void(* | le_event_HandlerFunc_t) (void *reportPtr) |
typedef void(* | le_event_LayeredHandlerFunc_t) (void *reportPtr, void *secondLayerFunc) |
typedef void(* | le_event_DeferredFunc_t) (void *param1Ptr, void *param2Ptr) |
typedef struct le_event_Handler * | le_event_HandlerRef_t |
Legato Event Loop API include file.
Copyright (C) Sierra Wireless Inc.
#define LE_CI_LINKAGE |
Initialization event handler function declaration macro.
Use this macro instead of a normal function prototype to create an Initialization Event Handler function. E.g.,
#define LE_COMPONENT_NAME le |
#define COMPONENT_INIT_PROTOTYPE | ( | name | ) |
Construct prototype of component init function.
#define COMPONENT_INIT_NAME CAT(CAT(_, LE_COMPONENT_NAME), _COMPONENT_INIT) |
Compose component initialization function name.
#define COMPONENT_INIT COMPONENT_INIT_PROTOTYPE(COMPONENT_INIT_NAME) |
Compose component initialization function prototype.
#define COMPONENT_INIT_ONCE_NAME CAT(COMPONENT_INIT_NAME, _ONCE) |
Compose one-time component initialization function name.
#define COMPONENT_INIT_ONCE COMPONENT_INIT_PROTOTYPE(COMPONENT_INIT_ONCE_NAME) |
Compose one-time component initialization function prototype.
#define LE_EVENT_INIT_HANDLER COMPONENT_INIT |
Deprecated name for COMPONENT_INIT.
typedef struct le_event_Id* le_event_Id_t |
Event ID.
An Event ID ties event reports to event handlers. See Publish-Subscribe Events for more details.
typedef void(* le_event_HandlerFunc_t) (void *reportPtr) |
Prototype for publish-subscribe event handler functions look like this:
reportPtr | [in] Pointer to the event report payload. |
typedef void(* le_event_LayeredHandlerFunc_t) (void *reportPtr, void *secondLayerFunc) |
Prototype for the first layer of a layered publish-subscribe event handler function look like this:
reportPtr | [in] Pointer to the event report payload. |
secondLayerFunc | [in] Address of the second layer handler function. |
typedef void(* le_event_DeferredFunc_t) (void *param1Ptr, void *param2Ptr) |
Prototype for deferred functions look like this:
param1Ptr | [in] Value passed in as param1Ptr to le_event_QueueFunction(). |
param2Ptr | [in] Value passed in as param2Ptr to le_event_QueueFunction(). |
See Deferred Function Calls for more information.
typedef struct le_event_Handler* le_event_HandlerRef_t |
Handler reference.
Used to refer to handlers that have been added for events. Only needed if you want to set the handler's context pointer or need to remove the handler later.
LE_DECLARE_INLINE le_event_Id_t le_event_CreateId | ( | const char * | name, |
size_t | payloadSize | ||
) |
Create a new event ID.
[in] | name | Name of the event ID. (Named for diagnostic purposes.) |
[in] | payloadSize | Data payload size (in bytes) of the event reports (can be 0). |
LE_DECLARE_INLINE le_event_Id_t le_event_CreateIdWithRefCounting | ( | const char * | name | ) |
Create a new event ID to report events where the payload is a pointer to a reference-counted memory pool object allocated using the Dynamic Memory Allocation API.
[in] | name | Name of the event ID. (Named for diagnostic purposes.) |
LE_DECLARE_INLINE le_event_HandlerRef_t le_event_AddHandler | ( | const char * | name, |
le_event_Id_t | eventId, | ||
le_event_HandlerFunc_t | handlerFunc | ||
) |
Adds a handler function for a publish-subscribe event ID.
Tells the calling thread event loop to call a specified handler function when a defined event reaches the front of the event queue.
[in] | name | Handler name. |
[in] | eventId | Event ID. |
[in] | handlerFunc | Handler function. |
LE_DECLARE_INLINE le_event_HandlerRef_t le_event_AddLayeredHandler | ( | const char * | name, |
le_event_Id_t | eventId, | ||
le_event_LayeredHandlerFunc_t | firstLayerFunc, | ||
void * | secondLayerFunc | ||
) |
Adds a layered handler function for a publish-subscribe event ID.
Tells the calling thread event loop to call a specified handler function when a defined event reaches the front of the event queue. Passes the required handler functions when called.
This is intended for use in implementing Layered Publish-Subscribe Handlers.
[in] | name | Handler name. |
[in] | name | Event ID. |
[in] | name | Pointer to first-layer handler func. |
[in] | name | Pointer to second-layer handler func. |
void le_event_RemoveHandler | ( | le_event_HandlerRef_t | handlerRef | ) |
Remove Handler
Removes a previously added event handler function.
[in] | handlerRef | Handler reference. |
void le_event_Report | ( | le_event_Id_t | eventId, |
void * | payloadPtr, | ||
size_t | payloadSize | ||
) |
Report an Event
Queues an Event Report to any and all event loops that have handlers for that event.
[in] | eventId | Event ID created using le_event_CreateId(). |
[in] | payloadPtr | Pointer to the payload bytes to be copied into the report. |
[in] | payloadSize | Number of bytes of payload to copy into the report. |
void le_event_ReportWithRefCounting | ( | le_event_Id_t | eventId, |
void * | objectPtr | ||
) |
Sends an Event Report with a pointer to a reference-counted object as its payload. The pointer must have been obtained from a memory pool using the Dynamic Memory Allocation API.
Calling this function passes ownership of the reference to the Event Loop API. The Event Loop API will ensure that the reference is properly counted while it passes through the event report dispatching system. Each handler will receive one counted reference to the object, so the handler is responsible for releasing the object when it is finished with it.
[in] | eventId | Event ID created using le_event_CreateIdWithRefCounting(). |
[in] | objectPtr | Pointer to an object allocated from a memory pool (using the Dynamic Memory Allocation API). |
void le_event_SetContextPtr | ( | le_event_HandlerRef_t | handlerRef, |
void * | contextPtr | ||
) |
Sets the context pointer for a given event handler.
This can later be retrieved using le_event_GetContextPtr() from within the handler function when it is called.
[in] | handlerRef | Handler where context pointer is to be set. |
[in] | contextPtr | Context pointer value. |
void* le_event_GetContextPtrFromRef | ( | le_event_HandlerRef_t | handlerRef | ) |
Fetches the context pointer for a given event handler.
[in] | handlerRef | Handler whose context pointer is to be set. |
void* le_event_GetContextPtr | ( | void | ) |
Fetches the context pointer for the currently running event handler.
Can only be called from within an event handler function.
void le_event_QueueFunction | ( | le_event_DeferredFunc_t | func, |
void * | param1Ptr, | ||
void * | param2Ptr | ||
) |
Queue a function onto the calling thread's Event Queue. When it reaches the head of the Event Queue, it will be called by the calling thread's Event Loop.
[in] | func | Function to be called later. |
[in] | param1Ptr | Value to be passed to the function when called. |
[in] | param2Ptr | Value to be passed to the function when called. |
void le_event_QueueFunctionToThread | ( | le_thread_Ref_t | thread, |
le_event_DeferredFunc_t | func, | ||
void * | param1Ptr, | ||
void * | param2Ptr | ||
) |
Queue a function onto a specific thread's Event Queue. When it reaches the head of that Event Queue, it will be called by that thread's Event Loop.
[in] | thread | Thread to queue the function to. |
[in] | func | The function. |
[in] | param1Ptr | Value to be passed to the function when called. |
[in] | param2Ptr | Value to be passed to the function when called. |
le_result_t le_event_QueueFunctionToThreadUnique | ( | le_thread_Ref_t | thread, |
le_event_DeferredFunc_t | func, | ||
void * | param1Ptr, | ||
void * | param2Ptr | ||
) |
Queue a function onto a specific thread's Event Queue if it isn't already on the Event Queue with the same parameters. When it reaches the head of that Event Queue, it will be called by that thread's Event Loop.
Using this function generally indicates poor design. It's generally better to ensure the event is only generated once, for example by disabling generating the event until the event handler is run.
[in] | thread | Thread to queue the function to. |
[in] | func | The function. |
[in] | param1Ptr | Value to be passed to the function when called. |
[in] | param2Ptr | Value to be passed to the function when called. |
void le_event_RunLoop | ( | void | ) |
Runs the event loop for the calling thread.
This starts processing events by the calling thread.
Can only be called once for each thread, and must never be called in the process's main thread.
LE_FULL_API int le_event_GetFd | ( | void | ) |
Fetches a file descriptor that will appear readable to poll(), select(), epoll_wait(), etc. when the calling thread's Event Loop needs servicing (via a call to le_event_ServiceLoop()).
LE_FULL_API le_result_t le_event_ServiceLoop | ( | void | ) |
Services the calling thread's Event Loop.
See also: le_event_GetFd().