framework/c/inc/le_eventLoop.h File Reference

Go to the source code of this file.

Defines
#define	COMPONENT_INIT   void _le_event_InitializeComponent(void)
#define	LE_EVENT_INIT_HANDLER   COMPONENT_INIT
	Deprecated name for COMPONENT_INIT.
#define	LE_EVENT_NUM_FD_EVENT_TYPES   6
	Number of members in the le_event_FdEventType_t enum.
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_FdHandlerFunc_t )(int fd)
typedef void(*	le_event_DeferredFunc_t )(void *param1Ptr, void *param2Ptr)
typedef struct le_event_FdMonitor *	le_event_FdMonitorRef_t
typedef struct le_event_Handler *	le_event_HandlerRef_t
typedef struct le_event_FdHandler *	le_event_FdHandlerRef_t
Enumerations
enum	le_event_FdEventType_t {   LE_EVENT_FD_READABLE, LE_EVENT_FD_READABLE_URGENT, LE_EVENT_FD_WRITEABLE, LE_EVENT_FD_WRITE_HANG_UP,   LE_EVENT_FD_READ_HANG_UP, LE_EVENT_FD_ERROR }
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_GetContextPtr (void)
le_event_FdMonitorRef_t	le_event_CreateFdMonitor (const char *name, int fd)
le_event_FdHandlerRef_t	le_event_SetFdHandler (le_event_FdMonitorRef_t monitorRef, le_event_FdEventType_t eventType, le_event_FdHandlerFunc_t handlerFunc)
void	le_event_SetFdHandlerContextPtr (le_event_FdHandlerRef_t handlerRef, void *contextPtr)
void	le_event_ClearFdHandler (le_event_FdHandlerRef_t handlerRef)
void	le_event_DeleteFdMonitor (le_event_FdMonitorRef_t monitorRef)
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)
void	le_event_RunLoop (void)
int	le_event_GetFd (void)
le_result_t	le_event_ServiceLoop (void)

---

Detailed Description

Legato Event Loop API include file.

Copyright (C) Sierra Wireless, Inc. 2013. All rights reserved. Use of this work is subject to license.

---

Define Documentation

#define COMPONENT_INIT   void _le_event_InitializeComponent(void)

Initialization event handler function declaration macro.

Use this macro instead of a normal function prototype to create an Initialization Event Handler function. E.g.,

 COMPONENT_INIT
 {
     // Do my initialization here...
 }

Returns:

Nothing.

---

Typedef Documentation

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.

typedef void(* le_event_FdHandlerFunc_t)(int fd)

Prototype for file descriptor event handler functions look like this:

Parameters:

fd	[in] File descriptor that experienced the event.

typedef struct le_event_FdHandler* le_event_FdHandlerRef_t

File Descriptor Handler reference.

Used to refer to handlers that have been set for File Descriptorevents. Only needed if you need to set te handler's context pointer or remove the handler later.

typedef struct le_event_FdMonitor* le_event_FdMonitorRef_t

File Descriptor Monitor reference.

Used to refer to File Descriptor Monitor objects.

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.

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.

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

---

Enumeration Type Documentation

enum le_event_FdEventType_t

Enumerates all the different types of events that can be generated for a file descriptor.

Enumerator:

LE_EVENT_FD_READABLE	Data is available for reading.
LE_EVENT_FD_READABLE_URGENT	Urgent/out-of-band data is available for reading.
LE_EVENT_FD_WRITEABLE	Ready to accept data for writing.
LE_EVENT_FD_WRITE_HANG_UP	Far end shutdown their reading while we were still writing.
LE_EVENT_FD_READ_HANG_UP	Far end shutdown their writing while we were still reading.
LE_EVENT_FD_ERROR	Experienced an error.

---

Function Documentation

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.

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.

Parameters:

[in]	name	Handler name.
[in]	eventId	Event ID.
[in]	handlerFunc	Handler function.

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.

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.

Parameters:

[in]	name	Handler name.
[in]	eventId	Event ID.
[in]	firstLayerFunc	Pointer to first-layer handler func.
[in]	secondLayerFunc	Pointer to second-layer handler func.

void le_event_ClearFdHandler

(

le_event_FdHandlerRef_t

handlerRef

)

Deregisters a handler for a file descriptor event.

Parameters:

[in]

handlerRef

Reference to the handler.

le_event_FdMonitorRef_t le_event_CreateFdMonitor	(	const char *	name,
		int	fd
	)

Creates a File Descriptor Monitor.

Creates an object that will monitor a given file descriptor for events.

The monitoring will be performed by the event loop of the thread that created the Monitor object. If that thread is blocked, no events will be detected for that file descriptor until that thread is unblocked and returns to its event loop.

Returns:

Reference to the object, which is needed for later deletion.

Note:

Doesn't return on failure, there's no need to check the return value for errors.

Parameters:

[in]	name	Name of the object (for diagnostics).
[in]	fd	File descriptor to be monitored for events.

le_event_Id_t le_event_CreateId	(	const char *	name,
		size_t	payloadSize
	)

Create a new event ID.

Returns:

Event ID.

Note:

Doesn't return on failure, there's no need to check the return value for errors.

Parameters:

[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_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.

Returns:

Event ID.

Note:

Doesn't return on failure, there's no need to check the return value for errors.

Parameters:

[in]

name

Name of the event ID. (Named for diagnostic purposes.)

void le_event_DeleteFdMonitor

(

le_event_FdMonitorRef_t

monitorRef

)

Deletes a file descriptor monitor object.

This will automatically remove all handlers added to the object.

Parameters:

[in]

monitorRef

Reference to the File Descriptor Monitor object.

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.

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.

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

Parameters:

[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_RemoveHandler

(

le_event_HandlerRef_t

handlerRef

)

Remove Handler

Removes a previously added event handler function.

Parameters:

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

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

Parameters:

[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_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_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.

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]	handlerRef	Handler where context pointer is to be set.
[in]	contextPtr	Context pointer value.

le_event_FdHandlerRef_t le_event_SetFdHandler	(	le_event_FdMonitorRef_t	monitorRef,
		le_event_FdEventType_t	eventType,
		le_event_FdHandlerFunc_t	handlerFunc
	)

Registers a handler for a specific type of file descriptor event with a given File Descriptor Monitor object.

When the handler function is called, it will be called by the the thread that registered the handler, which must also be the same thread that created the FD Monitor object.

Returns:

Reference to the handler function. (Only needed if the handler's context pointer needs to be set.)

Note:

• Doesn't return on failure, there's no need to check the return value for errors.
• The only way to deregister an FD Monitor event handler is to delete the FD Monitor object. Otherwise, there can be races between event reports and handler registration/deregistration that could result in spurious handler function calls.

Parameters:

[in]	monitorRef	Reference to the File Descriptor Monitor object.
[in]	eventType	Type of event to be reported to this handler.
[in]	handlerFunc	Handler function.

void le_event_SetFdHandlerContextPtr	(	le_event_FdHandlerRef_t	handlerRef,
		void *	contextPtr
	)

Sets the Context Pointer for a handler for a file descriptor event. This can be retrieved by the handler by calling le_event_GetContextPtr() when the handler function is running.

Parameters:

[in]	handlerRef	Reference to the handler.
[in]	contextPtr	Opaque context pointer value.