DataSource for C SDK  7.1.32.168791-9652659d
Managing Events

Typedefs

typedef struct _ds_io_event ds_except_event_t
 Opaque type defining an exception event. More...
 
typedef struct _ds_io_event ds_generic_event_t
 Opaque type defining a generic read/write event. More...
 
typedef int(* ds_io_event_cb) (sock_t sock, int val, void *data)
 Definition of the callback for use with read and write events. More...
 
typedef struct _ds_io_event ds_read_event_t
 Opaque type defining a read event. More...
 
typedef int(* ds_timed_event_cb) (int id, int val, void *data)
 Definition of the callback for use with timed events. More...
 
typedef struct _ds_timed_event ds_timed_event_t
 Opaque type defining a timed event. More...
 
typedef int(* ds_udp_event_cb) (int argc, char *argv[], int val, void *data)
 Definition of the callback for use with udp events. More...
 
typedef struct _ds_udp_event ds_udp_event_t
 Opaque type defining a udp event. More...
 
typedef struct _ds_io_event ds_write_event_t
 Opaque type defining a write event. More...
 

Functions

ds_except_event_tds_add_except_event (sock_t fd, ds_io_event_cb cb, int val, void *data)
 Add a socket exception event. More...
 
ds_timed_event_tds_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_tds_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_tds_add_read_event (sock_t fd, ds_io_event_cb cb, int val, void *data)
 Add a socket read event. More...
 
ds_timed_event_tds_add_timed_event (int id, double delay, ds_timed_event_cb cb, int val, void *data)
 Add a timed event. More...
 
ds_udp_event_tds_add_udp_event (const char *command, ds_udp_event_cb cb, int val, void *data)
 Add a udp event. More...
 
ds_write_event_tds_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...
 

Detailed Description

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:

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:

ds_add_read_event(sock, my_read_callback, 10, "Hello");

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.

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;
timed_ev = ds_add_timed_event(0, 1.0, timed_event_callback, 0, &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:

timed_ev = NULL;

Typedef Documentation

typedef struct _ds_io_event ds_except_event_t

Opaque type defining an exception event.

typedef struct _ds_io_event ds_generic_event_t

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
sockThe socket
valThe val argument given by ds_add_read_event()/ds_add_write_event() when adding this event
dataThe 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
typedef struct _ds_io_event ds_read_event_t

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
idThe id argument given by ds_add_timed_event() when adding this event
valThe val argument given by ds_add_timed_event() when adding this event
dataThe data argument given by ds_add_timed_event() when adding this event
Return values
0- Event should be removed
1- Event should not be removed
typedef struct _ds_timed_event ds_timed_event_t

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
argcNumber of arguments to this udp command
argvArguments, argv[0] is the name of the command
valThe val argument given by ds_add_udp_event() when adding this event
dataThe 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
typedef struct _ds_udp_event ds_udp_event_t

Opaque type defining a udp event.

typedef struct _ds_io_event ds_write_event_t

Opaque type defining a write event.

Function Documentation

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.

Parameters
fdThe socket file descriptor
cbThe function callback
valThe void pointer value to pass to the callback
dataThe 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
....
exceptevent = ds_add_except_event(sock,readevent_exec,0,NULL)
....
int exceptevent_exec(int fd, int val, void *data)
{
/* Process the exceptional event */
return 1;
}
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.

Parameters
starttimeNumber of minutes after midnight to run the timed event
periodPeriodicity between event calls
idAn integer ID
cbThe function callback
valThe integer value to pass to the callback
dataThe 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);
3 ...
4 int timedevent_exec(int id, int val, void *data)
5 {
6  // Return 0 or 1 depending on whether you wish the timed event to hap
7 pen again
8 ...
9 }
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.

Parameters
thenTime to use as the base calculation time (if 0, then now)
starttimeNumber of minutes after midnight to run the timed event
periodPeriodicity between event calls
idAn integer ID
cbThe function callback
valThe integer value to pass to the callback
dataThe 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.
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.

Parameters
fdThe socket file descriptor
cbThe function callback
valThe void pointer value to pass to the callback
dataThe 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
....
readevent = ds_add_read_event(sock,readevent_exec,0,NULL)
....
int readevent_exec(int fd, int val, void *data)
{
if ( read(fd,...) < 0 ) {
/* Close socket */
readevent = NULL
return 0; /* To remove the read event */
}
/* Do not remove the read event */
return 1;
}
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.

Parameters
idAn integer ID
delaySeconds before calling this event
cbThe function callback
valThe integer value to pass to the callback
dataThe 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);
3 ...
4 int timedevent_exec(int id, int val, void *data)
5 {
6  // Return 0 or 1 depending on whether you wish the timed event to happen again
7 ...
8 }
ds_udp_event_t* ds_add_udp_event ( const char *  command,
ds_udp_event_cb  cb,
int  val,
void *  data 
)

Add a udp event.

Parameters
commandUDP 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);
3 ...
4 int udpevent_exec(int argc, char *argv[], int val, void *data)
5 {
6  // Return 1 if you'd like to be called again or 0 to not be called again
7 }
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.

Parameters
fdThe socket file descriptor
cbThe function callback
valThe void pointer value to pass to the callback
dataThe void pointer value to pass to the callback
Returns
A ds_write_event_t object
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.

Parameters
periodPeriod that the event should run at
tevPointer to timed event (as returned by ds_add_periodic_event() or ds_add_timed_event())
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);
3 ...
4 int timedevent_exec(int id, int val, void *data)
5 {
6  ...
7  return (ds_check_periodic_event(1440,&periodicevent))
8 }
int ds_del_except_event ( ds_write_event_t ev)

Remove a socket except event.

Parameters
evThe 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
int ds_del_read_event ( ds_read_event_t ev)

Remove a socket read event.

Parameters
evThe 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
int ds_del_timed_event ( ds_timed_event_t ev)

Remove a timed event.

Parameters
evThe 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
void ds_del_udp_event ( ds_udp_event_t event)

Remove a timed event.

Parameters
eventThe timed event object to remove Example: Delete a previously registered udp event.
1 ds_del_udp_event(udpevent);
int ds_del_write_event ( ds_read_event_t ev)

Remove a socket write event.

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

Parameters
evThe ds_read_event_t to change the callback for
cbThe function callback
valThe void pointer value to pass to the callback
dataThe void pointer value to pass to the callback
void ds_set_timed_delay ( ds_timed_event_t ev,
double  delay 
)

Alter the delay for an existing timed event.

Parameters
evThe timed event object to alter
delayNew delay time in seconds

This can be used in two ways:

  1. Inside the timed event callback itself to alter the delay time of subsequent fires of this event.
  2. 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);
void ds_set_timed_delay_next ( ds_timed_event_t ev,
double  delay 
)

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

double ds_timed_event_get_fire_time ( ds_timed_event_t ev)

Return the time the event is due to fire.

Parameters
evThe event whose fire time shall be retrieved
Returns
Second Timestamp with fractional seconds representing the time the event is due to fire
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.

Parameters
evThe ds_timed_event_t to change the callback for
cbThe function callback
valThe void pointer value to pass to the callback
dataThe 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
commandto send
argvNULL 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;
ds_udpsignal_send_argv("debug",argv);
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.

Parameters
evThe ds_read_event_t to change the callback for
cbThe function callback
valThe void pointer value to pass to the callback
dataThe void pointer value to pass to the callback

Generated on Wed Oct 18 2023 17:20:33 for DataSource for C SDK