le_eventLoop.h File Reference

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

Construct prototype of component init function.

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.

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.

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.

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.

Event ID.

An Event ID ties event reports to event handlers. See Publish-Subscribe Events for more details.

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.

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]	name	Handler name.
[in]	eventId	Event ID.
[in]	handlerFunc	Handler 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.

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]	name	Handler name.
[in]	name	Event ID.
[in]	name	Pointer to first-layer handler func.
[in]	name	Pointer 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.

Create a new event ID.

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

Returns

Event ID.

Note

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

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]

name

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

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.

Fetches the context pointer for a given event handler.

Returns

The context pointer associated to the handlerRef.

Parameters

[in]

handlerRef

Handler whose context pointer is to be set.

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.

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.

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.

Remove Handler

Removes a previously added event handler function.

Parameters

[in]

handlerRef

Handler reference.

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.

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

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.

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.

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.