|
| ds_except_event_t * | ds_add_except_event (sock_t fd, ds_io_event_cb cb, int val, void *data) |
| | Add a socket exception event. More...
|
| |
| ds_timed_event_t * | ds_add_periodic_event (int starttime, int period, int id, ds_timed_event_cb cb, int val, void *data) |
| | Add a timed event, starting at a particular time. More...
|
| |
| ds_timed_event_t * | ds_add_periodic_event_from_time (time_t then, int starttime, int period, int id, ds_timed_event_cb cb, int val, void *data) |
| | Add a timed event, starting at a particular offset from a given time. More...
|
| |
| ds_read_event_t * | ds_add_read_event (sock_t fd, ds_io_event_cb cb, int val, void *data) |
| | Add a socket read event. More...
|
| |
| ds_timed_event_t * | ds_add_timed_event (int id, double delay, ds_timed_event_cb cb, int val, void *data) |
| | Add a timed event. More...
|
| |
| ds_udp_event_t * | ds_add_udp_event (const char *command, ds_udp_event_cb cb, int val, void *data) |
| | Add a udp event. More...
|
| |
| ds_write_event_t * | ds_add_write_event (sock_t fd, ds_io_event_cb cb, int val, void *data) |
| | Add a socket write event. More...
|
| |
| int | ds_check_periodic_event (int period, ds_timed_event_t **tev) |
| | Check a periodic to ensure that it runs at the appropriate time regardless of summertime. More...
|
| |
| int | ds_del_except_event (ds_write_event_t *ev) |
| | Remove a socket except event. More...
|
| |
| int | ds_del_except_event_free_data (ds_except_event_t *ev, void(*free_data)(int, void *)) |
| | Remove a socket except event. More...
|
| |
| int | ds_del_read_event (ds_read_event_t *ev) |
| | Remove a socket read event. More...
|
| |
| int | ds_del_read_event_free_data (ds_read_event_t *ev, void(*free_data)(int, void *)) |
| | Remove a socket read event. More...
|
| |
| int | ds_del_timed_event (ds_timed_event_t *ev) |
| | Remove a timed event. More...
|
| |
| int | ds_del_timed_event_free_data (ds_timed_event_t *ev, void(*free_data)(int, void *)) |
| | Remove a timed event. More...
|
| |
| void | ds_del_udp_event (ds_udp_event_t *event) |
| | Remove a timed event. More...
|
| |
| int | ds_del_write_event (ds_read_event_t *ev) |
| | Remove a socket write event. More...
|
| |
| int | ds_del_write_event_free_data (ds_write_event_t *ev, void(*free_data)(int, void *)) |
| | Remove a socket write event. More...
|
| |
| int | ds_get_gmt_offset (time_t t) |
| | Calculate offset between local time and gmt. More...
|
| |
| time_t | ds_get_time () |
| | Gets the current time in seconds. More...
|
| |
| struct tm * | ds_gmtime () |
| | Get the current time in GMT. More...
|
| |
| struct tm * | ds_localtime () |
| | Get the current time in the local timezone. More...
|
| |
| void | ds_read_event_set_callback (ds_read_event_t *ev, ds_io_event_cb cb, int val, void *data) |
| | Change the callback and callback values for a socket read event. More...
|
| |
| void | ds_set_timed_delay (ds_timed_event_t *ev, double delay) |
| | Alter the delay for an existing timed event. More...
|
| |
| void | ds_set_timed_delay_next (ds_timed_event_t *ev, double delay) |
| | Alter the next fire time for an existing timed event. More...
|
| |
| double | ds_timed_event_get_fire_time (ds_timed_event_t *ev) |
| | Return the time the event is due to fire. More...
|
| |
| void | ds_timed_event_set_callback (ds_timed_event_t *ev, ds_timed_event_cb cb, int val, void *data) |
| | Change the callback and callback values for a timed eent. More...
|
| |
| void | ds_udpsignal_send (const char *message) |
| | Send a udp message. More...
|
| |
| void | ds_udpsignal_send_argv (const char *command, char *argv[]) |
| | Send a UDP message. More...
|
| |
| void | ds_write_event_set_callback (ds_read_event_t *ev, ds_io_event_cb cb, int val, void *data) |
| | Change the callback and callback values for a socket write event. More...
|
| |
The DataSource library uses a custom event manager which allows asynchronous socket and timed events to be processed via registered function callbacks. There are two types of events:
- Timed events allow you to register a function callback to be called after a certain period of time.
- Socket read and write events allow you to register a function callback to be called when a socket is ready for reading or writing.
Both kinds of events use similar function callbacks which allow data to be given when the callback is registered; this data will be passed to the callback when it is called.
Event arguments
There are two arguments which are used to pass the data to the callback, which can be used either together, separately or not at all, giving maximum flexibility and ease of use:
For example, if you registered a socket read event with this call:
when sock is ready for reading, my_read_callback will be called with three arguments:
my_read_callback(sock, 10, "Hello");
The third parameter can be a pointer to any kind of data.
Return values
Both kinds of events use the return value of the function callback to determine what to do next.
- Timed event:
- If the callback returns 0 The event is removed and your callback will not be called again.
- If the callback returns 1 The event will be called again in the same amount of time as it was originally registered. This allows for an event to happen every n seconds.
- Socket event:
- If the callback returns 0 The event is removed and your callback will not be called again.
- If the callback returns 1 The event is left registered and the callback will be called as soon as more data is available to read or the socket is ready for writing.
Removal of Events
Events can be removed from any thread, including anonymous threads which aren't managed by DataSource.
Unfortunately, this opens up the potential of a race condition between the event being removed on one thread and firing on another. To this end, the user supplied callback must take some action to prevent the event being called erroneously (and a small amount of memory leaked).
The recommended way to resolve this, is to retain knowledge of event and check this on entry to the callback, for example for timed events:
ds_timed_event_t *timed_ev;
int timed_event_callback(int id, int val, void *data)
{
ds_timed_event_t **tev_ptr = data;
if ( *tev_ptr == NULL ) {
return -1;
}
}
Where the code to remove the timed event looks like this:
Opaque type defining an exception event.
Opaque type defining a generic read/write event.
| typedef int(* ds_io_event_cb) (sock_t sock, int val, void *data) |
Definition of the callback for use with read and write events.
- Parameters
-
| sock | The socket |
| val | The val argument given by ds_add_read_event()/ds_add_write_event() when adding this event |
| data | The data argument given by ds_add_read_event()/ds_add_write_event() when adding this event |
- Return values
-
| 0 | - Event should be removed |
| 1 | - Event should not be removed |
Opaque type defining a read event.
| typedef int(* ds_timed_event_cb) (int id, int val, void *data) |
Definition of the callback for use with timed events.
- Parameters
-
- Return values
-
| 0 | - Event should be removed |
| 1 | - Event should not be removed |
Opaque type defining a timed event.
| typedef int(* ds_udp_event_cb) (int argc, char *argv[], int val, void *data) |
Definition of the callback for use with udp events.
- Parameters
-
| argc | Number of arguments to this udp command |
| argv | Arguments, argv[0] is the name of the command |
| val | The val argument given by ds_add_udp_event() when adding this event |
| data | The data argument given by ds_add_udp_event() when adding this event |
- Return values
-
| 0 | - Event should be removed |
| 1 | - Event should not be removed |
Opaque type defining a udp event.
Opaque type defining a write event.
Add a socket exception event.
- Parameters
-
| fd | The socket file descriptor |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_read_event_t object
Example: Registering an exception event, where sock is an already established connection.
ds_except_event_t *exceptevent;
sock_t sock
....
....
int exceptevent_exec(int fd, int val, void *data)
{
return 1;
}
Add a timed event, starting at a particular time.
- Parameters
-
| starttime | Number of minutes after midnight to run the timed event |
| period | Periodicity between event calls |
| id | An integer ID |
| cb | The function callback |
| val | The integer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_timed_event_t object
- Note
- If starttime is >= 1440 then events will start at monday morning plus the time given. This allows for weekly events on a specific day.
-
This function wraps up ds_add_periodic_event_from_time() with a then parameter of time(NULL)
Example: Add an event to start at 1am and occur every hour.
1 ds_timed_event_t *periodicevent;
2 periodicevent = ds_add_periodic_event(60,5.0,0,timedevent_exec,0,NULL);
4 int timedevent_exec(int id, int val, void *data)
6 // Return 0 or 1 depending on whether you wish the timed event to hap
Add a timed event, starting at a particular offset from a given time.
- Parameters
-
| then | Time to use as the base calculation time (if 0, then now) |
| starttime | Number of minutes after midnight to run the timed event |
| period | Periodicity between event calls |
| id | An integer ID |
| cb | The function callback |
| val | The integer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_timed_event_t object
- Note
- If starttime is >= 1440 then events will start at monday morning plus the time given. This allows for weekly events on a specific day.
Add a socket read event.
- Parameters
-
| fd | The socket file descriptor |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_read_event_t object
Example: Registering read event, where sock is an already established connection.
ds_read_event_t *readevent;
sock_t sock
....
....
int readevent_exec(int fd, int val, void *data)
{
if ( read(fd,...) < 0 ) {
readevent = NULL
return 0;
}
return 1;
}
Add a timed event.
- Parameters
-
| id | An integer ID |
| delay | Seconds before calling this event |
| cb | The function callback |
| val | The integer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_timed_event_t object
Example: Add an event to call in 5 seconds.
1 ds_timed_event_t *timedevent;
2 timedevent = ds_add_timed_event(0,5.0,timedevent_exec,0,NULL);
4 int timedevent_exec(int id, int val, void *data)
6 // Return 0 or 1 depending on whether you wish the timed event to happen again
Add a udp event.
- Parameters
-
| command | UDP command to react to |
| cb | - Function callback |
| val | - Integer value to pass to the callback |
| data | - void pointer value to pass to the callback |
- Returns
- A ds_udp_event_t object
Example: Add a callback to respond on the udp message "test".
1 ds_udp_event_t *udpevent;
2 udpevent = ds_add_udp_event("test",udpevent_exec,0,NULL);
4 int udpevent_exec(int argc, char *argv[], int val, void *data)
6 // Return 1 if you'd like to be called again or 0 to not be called again
Add a socket write event.
- Parameters
-
| fd | The socket file descriptor |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
- Returns
- A ds_write_event_t object
Check a periodic to ensure that it runs at the appropriate time regardless of summertime.
- Parameters
-
- Return values
-
| 0 | - A new timed event has been added to ensure correct periodicity, *tev now contains a new timed event with the correct call time |
| 1 | - Supplied timed event will fire at the appropriate time |
This function checks to ensure that a timed event will occur at the same time everyday. Thus it should be used for timed events with a period of at least 1 day (1440 minutes).
The return value of the function should
Example: Check that a timed event will always occur at 2:30am every day.
1 ds_timed_event_t *periodicevent;
2 periodicevent = ds_add_periodic_event(150,1440.0,0,timedevent_exec,0,NULL);
4 int timedevent_exec(int id, int val, void *data)
7 return (ds_check_periodic_event(1440,&periodicevent))
Remove a socket except event.
- Parameters
-
| ev | The ds_except_event_t to remove |
- Returns
- 1 - always
| int ds_del_except_event_free_data |
( |
ds_except_event_t * |
ev, |
|
|
void(*)(int, void *) |
free_data |
|
) |
| |
Remove a socket except event.
This function allows you to delete an event from a thread other than the one it was registered on, but with the addition of a callback on the original thread to allow the caller to free the data registered with the event. The parameters passed to the callback are the same callback parameters used in the call to ds_add_except_event.
- Parameters
-
| ev | - The ds_except_event_t to remove |
| free_data | - Callback to free the data associated with this event |
- Returns
- 1 - always
Remove a socket read event.
- Parameters
-
| ev | The ds_read_event_t to remove |
- Returns
- 1 - always
| int ds_del_read_event_free_data |
( |
ds_read_event_t * |
ev, |
|
|
void(*)(int, void *) |
free_data |
|
) |
| |
Remove a socket read event.
This function allows you to delete an event from a thread other than the one it was registered on, but with the addition of a callback on the original thread to allow the caller to free the data registered with the event. The parameters passed to the callback are the same callback parameters used in the call to ds_add_read_event.
- Parameters
-
| ev | - The ds_read_event_t to remove |
| free_data | - Callback to free the data associated with this event |
- Returns
- 1 - always
Remove a timed event.
- Parameters
-
| ev | The timed event object to remove |
Example: Delete a previously registered timed event.
1 ds_del_timed_event(timedevent);
| int ds_del_timed_event_free_data |
( |
ds_timed_event_t * |
ev, |
|
|
void(*)(int, void *) |
free_data |
|
) |
| |
Remove a timed event.
This function allows you to delete an event from a thread other than the one it was registered on, but with the addition of a callback on the original thread to allow the caller to free the data registered with the event. The parameters passed to the callback are the same callback parameters used in the call to ds_add_write_event.
- Parameters
-
| ev | - The timed event object to remove |
| free_data | - Callback to free the data associated with this event |
- Returns
- 1 - always
Remove a timed event.
- Parameters
-
| event | The timed event object to remove Example: Delete a previously registered udp event. 1 ds_del_udp_event(udpevent); |
Remove a socket write event.
- Parameters
-
| ev | The ds_write_event_t to remove |
- Returns
- 1 - always
| int ds_del_write_event_free_data |
( |
ds_write_event_t * |
ev, |
|
|
void(*)(int, void *) |
free_data |
|
) |
| |
Remove a socket write event.
This function allows you to delete an event from a thread other than the one it was registered on, but with the addition of a callback on the original thread to allow the caller to free the data registered with the event. The parameters passed to the callback are the same callback parameters used in the call to ds_add_write_event.
- Parameters
-
| ev | - The ds_write_event_t to remove |
| free_data | - Callback to free the data associated with this event |
- Returns
- 1 - always
| int ds_get_gmt_offset |
( |
time_t |
t | ) |
|
Calculate offset between local time and gmt.
- Parameters
-
| t | time to calculate offset for |
- Returns
- offset in minutes
- Note
- Handles situation where offset spans midnight
| time_t ds_get_time |
( |
void |
| ) |
|
Gets the current time in seconds.
- Returns
- A time_t value representing the current time
| struct tm* ds_gmtime |
( |
void |
| ) |
|
Get the current time in GMT.
- Returns
- A struct tm representing the current GMT time
| struct tm* ds_localtime |
( |
void |
| ) |
|
Get the current time in the local timezone.
- Returns
- A struct tm representing the current time in the local timezone
Change the callback and callback values for a socket read event.
- Parameters
-
| ev | The ds_read_event_t to change the callback for |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
Alter the delay for an existing timed event.
- Parameters
-
| ev | The timed event object to alter |
| delay | New delay time in seconds |
This can be used in two ways:
- Inside the timed event callback itself to alter the delay time of subsequent fires of this event.
- Immediately after adding a timed event, to set the delay interval of recurring events. In this case the delay passed to ds_add_timed_event is only for the first fire of the event.
Example: Resetting the timed event timer so that happens every 5 seconds, starting in 10 seconds time.
1 timedevent = ds_add_timed_event(0, 10.0, callback, 0, NULL);
2 ds_set_timed_delay(timedevent, 5.0);
Alter the next fire time for an existing timed event.
- Parameters
-
| ev | - The timed event object to alter |
| delay | - The delay to apply to the timed event |
This can be used to set the delay to the next fire of the event without altering subsequent fires of the event
Return the time the event is due to fire.
- Parameters
-
| ev | The event whose fire time shall be retrieved |
- Returns
- Second Timestamp with fractional seconds representing the time the event is due to fire
Change the callback and callback values for a timed eent.
- Parameters
-
| ev | The ds_timed_event_t to change the callback for |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
| void ds_udpsignal_send |
( |
const char * |
message | ) |
|
Send a udp message.
- Parameters
-
| message | - The relevant udp message |
The message should consist of the command and any additional parameters as appropriate, eg:
1 ds_udpsignal_send("debug DEBUG");
would change the current dbeug level to DEBUG, if this command is supported by your DataSource application
| void ds_udpsignal_send_argv |
( |
const char * |
command, |
|
|
char * |
argv[] |
|
) |
| |
Send a UDP message.
- Parameters
-
| command | to send |
| argv | NULL terminated array of char * pointers |
The maximum length of the message is limited to 2048 bytes
Example: Setting the debug level of your DataSource application.
char *argv[2];
argv[0] = "DEBUG";
argv[1] = NULL;
Change the callback and callback values for a socket write event.
- Parameters
-
| ev | The ds_read_event_t to change the callback for |
| cb | The function callback |
| val | The void pointer value to pass to the callback |
| data | The void pointer value to pass to the callback |
