Fast Event Library Documentation

Download Source in .tar.gz
Download Source in .zip
    Download Test Programs:
             thread1.c
             thread2.c
             thread3.c
             thread4.c
Part1: Fast Event Processing in SDL

The obvious next step in a story like this one is to take the test code and turn it into a general purpose library. So, I did. The library is very small and has the name of FastEvents. You can download the complete library along with a GNU/Linux makefile file and a test application using the links at the top of the page.

The functions in the fast events library fall in two distinct groups, the first group, FE_Init(), FE_Quit(), and FE_GetError() are house keeping functions used to start and stop the library and report errors generated by the library. The second class of functions are a direct replacement for the SDL functions SDL_PumpEvents(), SDL_PollEvent(), SDL_WaitEvent(), and SDL_PushEvent(). In your program if you use these SDL functions you can not also use the fast event library functions and vice versa. It is also not permitted to use SDL_PeepEvents() with the fast event library. But, then using any kind of peep events function is a bad idea at any time.

The thread4.c program gives an example of how to use these functions in an SDL program.

Linux, Windows, and MacOS

There are slight differences between each of these platforms that effect the fast events library.

Linux - You must include SDL_INIT_EVENTTHREAD in your call to SDL_Init(). It will not work without it.
Windows - You must not include SDL_INIT_EVENTTHREAD in your call to SDL_Init(). This option and is not supported and not needed on Windows.
MacOS - MacOS 10 is the first MacOS to properly support threads. The fast events library will not work on any earlier version.

All the sample code is written to work on Linux, you may have to modify it to make it work on Windows.

int FE_Init();

FE_Init() initializes the fast events library. It creates the mutex, condition variable, and timer used by the library. Because it uses SDL functions it must be called after SDL_Init() is called and before any other fast event library routines are called. Using any other fast event library functions before calling FE_Init() will crash your program.

On exit it returns -1 (negative one) if it failed to initialize the library and 0 (zero) if the library was correctly initialized. If an error occurred a text description of the error can be retrieved using FE_GetError(). The documentation for FE_GetError() includes a list of all fast event library error messages.

void FE_Quit();

FE_Quit() cleans up the resources used by the fast event library and shuts down the library. It must be called before any call to SDL_Quit(). After FE_Quit() is called any use of fast events library will crash your program.

char *FE_GetError();

FE_GetError() returns a pointer to a string that describes the last error that occurred. If no error has occurred it returns NULL. The errors that can currently be returned by this function are:

FE: can't create a mutex - For some unknown reason the library was not able to create a mutex. This usually means that you are running on a system that does not support multiple threads. It could also indicate that you have memory corruption problems, or that you have not called SDL_Init().
FE: can't create a condition variable - For some unknown reason the library can not create a condition variable. This usually means that you are running on a system that does not support multiple threads. It could also indicate that you have memory corruption problems, or that you have not called SDL_Init().
FE: can't add a timer - There is no good reason why this should ever happen, but since the library needs a timer to poll for input events the library can't do its job with out a timer and must quit.

void FE_PumpEvents();

FE_PumpEvents() does exactly the same thing that SDL_PumpEvents() does. It forces SDL to check all the input devices and push their events on the queue. There is rarely any reason to use this function with the fast event library because FE_PollEvent() and FE_WaitEvent() are designed to do this for you.

This function should only be called from the thread that initialized SDL.

int FE_PollEvent(SDL_Event *event);

FE_PollEvent() checks to see if there are any events in the event queue. If the queue is empty it returns 0, if there are events available FE_PollEvent returns 1, if an error occurred during event processing it returns -1. If there are events in the queue and *event is not NULL, then the first event on the queue is copied to *event and removed from the queue. If *event is not NULL and not pointing to an SDL_Event structure, memory will be corrupted.

Unlike FE_WaitEvent(), FE_PollEvent() always returns immediately.

This function should only be called from the thread that initialized SDL.

int FE_WaitEvent(SDL_Event *event);

FE_WaitEvent() checks the event queue and if there are events in the queue the first event is copied to *event and removed from the queue. If there are no events in the queue then this function waits until an event is placed in the queue. This function always returns 1. If no events occur or if there are permanent errors in the event handling system, this function will never return.

This function must only be called from the thread that initialized SDL.

int FE_PushEvent(SDL_Event *event);

FE_PushEvent() appends the contents of the structure pointed to by *event at the end of the queue. If the queue is full then FE_PushEvent() waits until there is room in the queue for the event. Unlike SDL_PushEvent() when this function returns the event is in the queue. FE_PushEvent() may be called from any thread and is a good way for threads to communicate with the main thread. On return this function always returns 1.

Because FE_PushEvent() may have to wait for the queue to empty you can get into a dead lock if you try to append an event on to a full queue from the thread that processes events. For that reason I do not recommend using this function in the main thread of an SDL program.