le_eventLoop.h File Reference

#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.
 
#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.
 

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
 

Functions

le_event_Id_t le_event_CreateId (const char *name, size_t payloadSize)
 
le_event_Id_t le_event_CreateIdWithRefCounting (const char *name)
 
le_event_HandlerRef_t le_event_AddHandler (const char *name, le_event_Id_t eventId, le_event_HandlerFunc_t handlerFunc)
 
le_event_HandlerRef_t le_event_AddLayeredHandler (const char *name, le_event_Id_t eventId, le_event_LayeredHandlerFunc_t firstLayerFunc, void *secondLayerFunc)
 
void le_event_RemoveHandler (le_event_HandlerRef_t handlerRef)
 
void le_event_Report (le_event_Id_t eventId, void *payloadPtr, size_t payloadSize)
 
void le_event_ReportWithRefCounting (le_event_Id_t eventId, void *objectPtr)
 
void le_event_SetContextPtr (le_event_HandlerRef_t handlerRef, void *contextPtr)
 
void * le_event_GetContextPtrFromRef (le_event_HandlerRef_t handlerRef)
 
void * le_event_GetContextPtr (void)
 
void le_event_QueueFunction (le_event_DeferredFunc_t func, void *param1Ptr, void *param2Ptr)
 
void le_event_QueueFunctionToThread (le_thread_Ref_t thread, le_event_DeferredFunc_t func, void *param1Ptr, void *param2Ptr)
 
le_result_t le_event_QueueFunctionToThreadUnique (le_thread_Ref_t thread, le_event_DeferredFunc_t func, void *param1Ptr, void *param2Ptr)
 
void le_event_RunLoop (void)
 
LE_FULL_API int le_event_GetFd (void)
 
LE_FULL_API le_result_t le_event_ServiceLoop (void)
 

Detailed Description

Legato Event Loop API include file.

Macro Definition Documentation

◆ COMPONENT_INIT_PROTOTYPE

#define COMPONENT_INIT_PROTOTYPE (   name)
Value:
( \
__attribute__((unused)) void *param1Ptr, \
__attribute__((unused)) void *param2Ptr \
)
#define LE_SHARED
Definition: le_basics.h:287
#define LE_CI_LINKAGE
Definition: le_eventLoop.h:544

Construct prototype of component init function.

◆ LE_CI_LINKAGE

#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.,

{
// Do my initialization here...
}
Returns
Nothing.

Typedef Documentation

◆ le_event_DeferredFunc_t

typedef void(* le_event_DeferredFunc_t) (void *param1Ptr, void *param2Ptr)

Prototype for deferred functions look like this:

Parameters
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.

◆ le_event_HandlerFunc_t

typedef void(* le_event_HandlerFunc_t) (void *reportPtr)

Prototype for publish-subscribe event handler functions look like this:

Parameters
reportPtr[in] Pointer to the event report payload.
Warning
The reportPtr is only valid until the handler function returns.

◆ le_event_HandlerRef_t

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_event_Id_t

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.

◆ le_event_LayeredHandlerFunc_t

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:

Parameters
reportPtr[in] Pointer to the event report payload.
secondLayerFunc[in] Address of the second layer handler function.
Warning
The reportPtr is only valid until the handler function returns.

Function Documentation

◆ le_event_AddHandler()

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.

Parameters
[in]nameHandler name.
[in]eventIdEvent ID.
[in]handlerFuncHandler function.
Returns
Handler reference, only needed to remove the handler (using le_event_RemoveHandler() ). Can be ignored if the handler will never be removed.
Note
Doesn't return on failure, there's no need to check the return value for errors.

◆ le_event_AddLayeredHandler()

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.

Parameters
[in]nameHandler name.
[in]nameEvent ID.
[in]namePointer to first-layer handler func.
[in]namePointer to second-layer handler func.
Returns
Handler reference, only needed for later removal of the handler (using le_event_RemoveHandler() ). Can be ignored if the handler will never be removed.
Note
Doesn't return on failure, there's no need to check the return value for errors.

◆ le_event_CreateId()

le_event_Id_t le_event_CreateId ( const char *  name,
size_t  payloadSize 
)

Create a new event ID.

Parameters
[in]nameName of the event ID. (Named for diagnostic purposes.)
[in]payloadSizeData payload size (in bytes) of the event reports (can be 0).
Returns
Event ID.
Note
Doesn't return on failure, there's no need to check the return value for errors.

◆ le_event_CreateIdWithRefCounting()

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.

Parameters
[in]nameName of the event ID. (Named for diagnostic purposes.)
Returns
Event ID.
Note
Doesn't return on failure, there's no need to check the return value for errors.

◆ le_event_GetContextPtr()

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.

Returns
Context pointer that was set using le_event_SetContextPtr(), or NULL if le_event_SetContextPtr() was not called.

◆ le_event_GetContextPtrFromRef()

void* le_event_GetContextPtrFromRef ( le_event_HandlerRef_t  handlerRef)

Fetches the context pointer for a given event handler.

Returns
The context pointer associated to the handlerRef.
Parameters
[in]handlerRefHandler whose context pointer is to be set.

◆ le_event_GetFd()

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()).

Warning
Only intended for use when integrating with legacy POSIX-based software that cannot be easily refactored to use the Legato Event Loop. The preferred approach is to call le_event_RunLoop().
Returns
The file descriptor.

◆ le_event_QueueFunction()

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.

Parameters
[in]funcFunction to be called later.
[in]param1PtrValue to be passed to the function when called.
[in]param2PtrValue to be passed to the function when called.

◆ le_event_QueueFunctionToThread()

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.

Parameters
[in]threadThread to queue the function to.
[in]funcThe function.
[in]param1PtrValue to be passed to the function when called.
[in]param2PtrValue to be passed to the function when called.

◆ le_event_QueueFunctionToThreadUnique()

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.

Returns
LE_OK if the function was queued to the Event Queue
LE_DUPLICATE if the function was already in the Event Queue
Parameters
[in]threadThread to queue the function to.
[in]funcThe function.
[in]param1PtrValue to be passed to the function when called.
[in]param2PtrValue to be passed to the function when called.

◆ le_event_RemoveHandler()

void le_event_RemoveHandler ( le_event_HandlerRef_t  handlerRef)

Remove Handler

Removes a previously added event handler function.

Parameters
[in]handlerRefHandler reference.

◆ le_event_Report()

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.

Note
Copies the event report payload, so it is safe to release or reuse the buffer that payloadPtr points to as soon as le_event_Report() returns.
Parameters
[in]eventIdEvent ID created using le_event_CreateId().
[in]payloadPtrPointer to the payload bytes to be copied into the report.
[in]payloadSizeNumber of bytes of payload to copy into the report.

◆ le_event_ReportWithRefCounting()

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.

Parameters
[in]eventIdEvent ID created using le_event_CreateIdWithRefCounting().
[in]objectPtrPointer to an object allocated from a memory pool (using the Dynamic Memory Allocation API).

◆ le_event_RunLoop()

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.

Note
Function never returns.

◆ le_event_ServiceLoop()

LE_FULL_API le_result_t le_event_ServiceLoop ( void  )

Services the calling thread's Event Loop.

Warning
Only intended for use when integrating with legacy POSIX-based software that can't be easily refactored to use the Legato Event Loop. The preferred approach is to call le_event_RunLoop().

See also: le_event_GetFd().

Returns
  • LE_OK if there is more to be done. DO NOT GO BACK TO SLEEP without calling le_event_ServiceLoop() again.
  • LE_WOULD_BLOCK if there is nothing left to do for now and it is safe to go back to sleep.

◆ le_event_SetContextPtr()

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.

Parameters
[in]handlerRefHandler where context pointer is to be set.
[in]contextPtrContext pointer value.