rmain - Roy main loop functions

#include <roy.h>

void rmain (void);

void rmain_quit (void);

int rmain_timeout_add (unsigned int ms, char *description, RMainTimeoutEventFunction function, void *user_data);

int rmain_idle_add (char *description, RMainIdleEventFunction function, void *user_data);

int rmain_fd_add (int fd, char *description, RMainEventType event_types, RMainFDEventFunction function, void *user_data);

int rmain_socket_add (SOCKET fd, char *description, RMainEventType event_types, RMainSocketEventFunction function, void *user_data);

void rmain_remove (int id);

char * rmain_description (int id);

Rmain implements a fairly standard, event driven mainloop. Entries of various types are added via the add functions above. rmain(3) is then called, and when events occur as defined by the added entries, the applicable callback function is called, alerting the programmer to the event.

A call to rmain_timeout_add(3) will add a timeout event to the mainloop. ms is the number of milliseconds before the callback function is called. description is the description of this entry, as used for debugging purposes. function is a pointer to the callback function, and user_data is a pointer to any data you wish to have available in the callback function. The timeout callback function (of course the name can be of your choosing) should be declared as:

    void rmain_timeout_callback (int id, void *user_data);

A call to rmain_idle_add(3) creates a new entry that will be called whenever something else is not being done in the mainloop. In the event of multiple idle events, each will be called in sequence one after the other. Arguments are identical to rmain_timeout_add(3). The timeout_add callback should be defined as:

    void rmain_idle_callback (int id, void *user_data);

rmain_fd_add(3) adds a file descriptor to the mainloop for watching. fd is the file descriptor to watch, and event_types should contain one or both of the flags TMAIN_READ and/or TMAIN_WRITE, depending on if you wish to watch for the readiness of the file descriptor for reading, or writing, or both. The callback function for rmain_fd_add should be defined as:

    void rmain_fd_callback (int id, int fd, 
                            RMainEventType event_type,
                            void *user_data);

Where event_type will contain the flags which caused this callback to be called. Again, one of TMAIN_READ or TMAIN_WRITE

rmain_socket_add(3) is identical to rmain_fd_add(3), but is used for sockets descriptors. This is done for compatability with winsock sockets which have a different socket type. The callback function for rmain_socket_add(3) is identical to that for rmain_fd_add(3).

rmain_description(3) returns the description of the entry as passed in during creation. id is the id returned from the creation function.

rmain_remove(3) removes an entry from the mainloop, and frees any associated memory. It will not close file descriptors or sockets.

rmain_quit(3) exits the mainloop and allows program flow to continue passed the call to rmain(3).

rmain(3) starts the mainloop. After calling this function it will remain in control until rmain_quit(3) is called.

All the add functions return an integer id that represents that entry in the mainloop. rmain_description() returns a string containing the description of the entry id.

None of these functions produce any errors. If an error occurs on a socket, the callback will be called with whatever status was being checked for, and will then fail in the read, write, recv, or send call, which should check for errors.

The rmain loop uses the rdebug(3) facility to log debugging notices. Adding 'rmain' to the rdebug_enable(3) domains argument will print verbose status information about each entry, identified by its description.

roy(3), rdebug(3)