File	Date	Author	Commit
src	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn
www	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn
ChangeLog	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn
INSTALL	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn
README	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn
TODO	2013-06-18	Peter R. Torpman	[d229ae] added the code from svn

Read Me

==========================================================================
= README                                                              
==========================================================================

After I had spent some time trying to write a useful library that 
implements a "usability-layer" on top of the POSIX real-time timers,
I figured that, since it took me so long to find stuff out, maybe I should
share my results with you people. So I did. And, here is the result:

          *** POSIX Real Time Timers Utility Library (PRT) ***

--------------------------------------------------------------------------
= WHY THIS LIBRARY?
--------------------------------------------------------------------------

PRT uses only one real-time timer from the system. PRT keeps an internal 
list of timers and only the one, that is first in line, gets one of the 
systems real-time timers. 

Other than that, it's easy to use - at the moment only three functions
make up the API.

And (!), when a timer fires, a user-provided callback will be called.

--------------------------------------------------------------------------
= API
--------------------------------------------------------------------------

*** prt_timer_add()

  This function will add a timer to the PRT internal list. If it ends up
  at the beginning of the list, a real-time timer will be started using
  the timer_create() function.

  If it does not become the first in line, it will have to wait in line
  for its turn.

  Parameters to this function are:

  * A time value specifying how many milliseconds until the timer should
    fire.
  * A callback to be called when the timer fired.
  * Client data, i.e any arbitrary information (in the form of a pointer)
    that the user would like to have returned when the timer fires and 
    the callback is called.

  The function returns a pointer to timer handle, that should be used when
  removing or re-setting the timer.

*** prt_timer_del()

  This function will remove the timer from the list.

  Parameter to this function is:

  * The handle returned in prt_timer_add().

  The function will return 0 if everything went fine, otherwise, an error
  code will be returned.

*** prt_timer_set()

  This function allows the user to change the timer to fire at a different
  point of time (offset from now), and the client data.

  Parameters to this function are:

  * A time value specifying how many milliseconds until the timer should
    fire.
  * Client data, i.e any arbitrary information (in the form of a pointer)
    that the user would like to have returned when the timer fires and 
    the callback is called.

  The function will return 0 if everything went fine, otherwise, an error
  code will be returned.


--------------------------------------------------------------------------
= WEIRD SH*T
--------------------------------------------------------------------------

For some reason when compiling the library with -O2 turned on for GCC,
my test program breaks with a GPF in libpthread. Any help with finding 
the fault is appreciated.