TizenRT Public API  v2.0 M2
Eventloop

Provides APIs for Eventloop. More...

Files

file  eventloop.h
 

Macros

#define EVENTLOOP_CALLBACK_STOP   0
 Return value of callback function for event. More...
 

Typedefs

typedef uv_timer_t el_timer_t
 EventLoop Timer structure. More...
 
typedef uv_loop_t el_loop_t
 EventLoop Loop structure. More...
 
typedef uv_signal_t el_event_t
 EventLoop Event structure. More...
 
typedef bool(* timeout_callback) (void *data)
 EventLoop Timeout Callback. More...
 
typedef void(* thread_safe_callback) (void *data)
 EventLoop Thread Safe Callback. More...
 
typedef bool(* event_callback) (void *registered_cb_data, void *received_event_data)
 EventLoop Event Callback This is specific type for callback function used in eventloop_add_event_handler.
When some tasks send event, registered callback functions are called with some data.
The first parameter, registered_cb_data is function data registered in eventloop_add_event_handler.
The second parameter, received_event_data is data received from event sender.
. More...
 

Enumerations

Functions

el_timer_teventloop_add_timer (unsigned int timeout, bool repeat, timeout_callback func, void *cb_data)
 Create timer to call the function in the given period of time. More...
 
int eventloop_delete_timer (el_timer_t *timer)
 Delete specific timer. More...
 
el_timer_teventloop_add_timer_async (unsigned int timeout, bool repeat, timeout_callback func, void *cb_data)
 Create timer to call the function in the given period of time asynchronously. More...
 
el_event_teventloop_add_event_handler (int type, event_callback func, void *cb_data)
 Set event callback which will be called a certain event occur. More...
 
int eventloop_del_event_handler (el_event_t *handle)
 Delete registered handler for event. More...
 
int eventloop_send_event (int type, void *event_data, int data_size)
 Send an event. More...
 
int eventloop_loop_run (void)
 Run the loop of its own task. More...
 
int eventloop_loop_stop (void)
 Stop the loop of its own task. More...
 
int eventloop_thread_safe_function_call (thread_safe_callback func, void *cb_data)
 Callback is added at the each eventloop to be called thread safely.
. More...
 

Detailed Description

Provides APIs for Eventloop.

Macro Definition Documentation

#define EVENTLOOP_CALLBACK_STOP   0

Return value of callback function for event.

The callback function should return EVENTLOOP_CALLBACK_STOP(false) or EVENTLOOP_CALLBACK_CONTINUE(true).
It decides whether continuing to execute callback function for the event or not.
If it returns EVENTLOOP_CALLBACK_STOP, receiving registered events is stopped.
The registered handler won't be executed from now on although receiving the event.
Otherwise, a callback function is called continuously.

Definition at line 78 of file eventloop.h.

Typedef Documentation

typedef uv_signal_t el_event_t

EventLoop Event structure.

Definition at line 94 of file eventloop.h.

typedef uv_loop_t el_loop_t

EventLoop Loop structure.

Definition at line 89 of file eventloop.h.

typedef uv_timer_t el_timer_t

EventLoop Timer structure.

Definition at line 84 of file eventloop.h.

typedef bool(* event_callback) (void *registered_cb_data, void *received_event_data)

EventLoop Event Callback This is specific type for callback function used in eventloop_add_event_handler.
When some tasks send event, registered callback functions are called with some data.
The first parameter, registered_cb_data is function data registered in eventloop_add_event_handler.
The second parameter, received_event_data is data received from event sender.
.

Definition at line 113 of file eventloop.h.

typedef void(* thread_safe_callback) (void *data)

EventLoop Thread Safe Callback.

Definition at line 104 of file eventloop.h.

typedef bool(* timeout_callback) (void *data)

EventLoop Timeout Callback.

Definition at line 99 of file eventloop.h.

Enumeration Type Documentation

Event type used in Event Loop.

Event loop uses these values as event types.
If user wants to use new events, those should be defined ahead.
An example of a pre-defined events are shown below.

enum el_event_type_e {
EL_EVENT_WIFI_ON = 1,
EL_EVENT_WIFI_OFF = 2,
EL_EVENT_PRE_DEFINE = 3,
EL_EVENT_MAX,
};

Definition at line 64 of file eventloop.h.

Error Type of Result Value returned from Event Loop.

If operation is failed, these defined values will be returned.

Definition at line 41 of file eventloop.h.

Function Documentation

el_event_t* eventloop_add_event_handler ( int  type,
event_callback  func,
void *  cb_data 
)

Set event callback which will be called a certain event occur.

#include <eventloop/eventloop.h>
This API is almost similar to task_manager_set_broadcast_cb. The difference between them is a context when callback function is executed.
In case of task manager, the callback function is executed by task manager if someone sends some events.
On the other hands, the callback functions of eventloop are called by polling the events in loop by itself.
So you should run loop by calling eventloop_loop_run to receive event after calling this API.
And you can continue or stop to execution of callback function depending on return value of callback function.
Please refer to a description of EVENTLOOP_CALLBACK_STOP and EVENTLOOP_CALLBACK_CONTINUE.
Finally when returned handle is not needed anymore or all works you want are done, you should call eventloop_del_event_handler.
Because some resources for event handler are allocated internally, you should free them.

Remarks
User should NOT free the data passed to callback function before callback function is finished.
It means that user should free them in callback function before it returns EVENTLOOP_CALLBACK_STOP or after eventloop_loop_run()
Parameters
[in]typea value of event type
[in]functhe callback function to be called
It has specific type, event_callback which has two types of data as parameter.
The first parameter is data registered in this call and the second parameter is data received from sender.
And, it should return EVENTLOOP_CALLBACK_STOP(false) or EVENTLOOP_CALLBACK_CONTINUE(true).
[in]cb_datadata to pass to func when func is called
Returns
On success, A pointer of created event handle is returned. On failure, NULL is returned
Since
TizenRT v2.1 PRE
el_timer_t* eventloop_add_timer ( unsigned int  timeout,
bool  repeat,
timeout_callback  func,
void *  cb_data 
)

Create timer to call the function in the given period of time.

#include <eventloop/eventloop.h>
This API can create timer which is called once or repeated according to repeat flag.
The timer event is handled in the loop of its own task by calling eventloop_loop_run.
All resources created for timer at this call is freed when timer is stopped.
So you don't have to call eventloop_delete_timer after it is stopped.
In case of repeated timer, it can be stopped by calling eventloop_delete_timer or by returning EVENTLOOP_CALLBACK_STOP in callback function.
In other case, timer is stopped after calling callback function once regardless of return value in callback function.

Remarks
User should NOT free the data passed to callback function before callback function is finished.
It means that user should free them in callback function before it returns EVENTLOOP_CALLBACK_STOP or after eventloop_loop_run()
Parameters
[in]timeoutinterval in milliseconds from the current time of loop for calling callback function
[in]repeatthe value which represents whether timer runs repeatedly or not.
You can stop the periodic timer by calling eventloop_delete_timer
[in]functhe callback function to be called In case of repeated timer, it should return EVENTLOOP_CALLBACK_STOP(false) or EVENTLOOP_CALLBACK_CONTINUE(true).
[in]cb_datadata to pass to func when func is called
Returns
On success, A pointer of created timer is returned. On failure, NULL is returned
Since
TizenRT v2.1 PRE
el_timer_t* eventloop_add_timer_async ( unsigned int  timeout,
bool  repeat,
timeout_callback  func,
void *  cb_data 
)

Create timer to call the function in the given period of time asynchronously.

#include <eventloop/eventloop.h>
This API is same as eventloop_add_timer(), but it yields the event to event loop task.
So you don't need to call eventloop_loop_run() to run loop.
In other words, the timer event is added to a loop handled by eventloop task,
and then registered callback is executed in the context of eventloop task asynchronously, not task which created timer.
All resources created for timer at this call is freed when timer is stopped.
So you don't have to call eventloop_delete_timer after it is stopped.
In case of repeated timer, it can be stopped by calling eventloop_delete_timer or by returning EVENTLOOP_CALLBACK_STOP in callback function.
In other case, timer is stopped after calling callback function once. regardless of return value in callback function.

Remarks
User should NOT free the data passed to callback function before callback function is finished.
Therefore, user should free them in callback function before it returns EVENTLOOP_CALLBACK_STOP.
Parameters
[in]timeoutinterval in milliseconds from the current time of loop for calling callback function
[in]repeatthe value which represents whether timer runs repeatedly or not.
You can stop the periodic timer by calling eventloop_delete_timer
[in]functhe callback function to be called
[in]cb_datadata to pass to func when func is called
Returns
On success, A pointer of created timer is returned. On failure, NULL is returned
Since
TizenRT v2.1 PRE
int eventloop_del_event_handler ( el_event_t handle)

Delete registered handler for event.

#include <eventloop/eventloop.h>
The registered event handler is deleted and all used resources for event handler are freed.

Parameters
[in]handlea pointer of event handle to be deleted
Returns
On success, OK is returned. On failure, defined negative value is returned
Since
TizenRT v2.1 PRE
int eventloop_delete_timer ( el_timer_t timer)

Delete specific timer.

#include <eventloop/eventloop.h>
The timer is stopped if it is active and all used resources for timer are freed

Parameters
[in]timerA pointer of timer to be deleted
Returns
On success, OK is returned. On failure, defined negative value is returned
Since
TizenRT v2.1 PRE
int eventloop_loop_run ( void  )

Run the loop of its own task.

#include <eventloop/eventloop.h>

Parameters
[in]None
Returns
On success, OK is returned. On failure, defined negative value is returned.
If eventloop_loop_stop() was called and there are still active works, EVENTLOOP_NOT_FINISHED is returned
Since
TizenRT v2.1 PRE
int eventloop_loop_stop ( void  )

Stop the loop of its own task.

#include <eventloop/eventloop.h>

Parameters
[in]None
Returns
On success, OK is returned. On failure, defined negative value is returned
Since
TizenRT v2.1 PRE
int eventloop_send_event ( int  type,
void *  event_data,
int  data_size 
)

Send an event.

#include <eventloop/eventloop.h>
This API is almost similar to task_manager_broadcast.
The event will be sent with some data to tasks which registed handler for this event.
And then registered callback functions will be executed when they are polling events.

Parameters
[in]typea value of event type
[in]event_datadata to be passed to registered handler together
[in]data_sizesize of data
Returns
On success, OK is returned. On failure, defined negative value is returned
Since
TizenRT v2.1 PRE
int eventloop_thread_safe_function_call ( thread_safe_callback  func,
void *  cb_data 
)

Callback is added at the each eventloop to be called thread safely.
.

#include <eventloop/eventloop.h>

Remarks
User should NOT free the data passed to callback function before callback function is finished.
It means that user should free them in callback function or free them after eventloop_loop_run()
Parameters
[in]functhe callback function to be called
[in]cb_datadata to pass to func when func is called
Returns
On success, OK is returned. On failure, defined negative value is returned
Since
TizenRT v2.1 PRE