Thread and Timer Library

#timers.h

Timers requires threads, so threads is introduced as part of the timer library. Some simple thread operations are also added in timers, [Enter/Leave]CriticalSec() for thread interlocks.

CPROC is generally almost always used when specifying external code, or code that the library will call back into. The library itself sometimes omits it no its own internal definitions, but generally the library is all CPROC. CPROC is a macro alias for __cdecl, which defined the calling convention.

##Threads

This is a simple library, that aliases CreateThread, beginthreadex, pthread_create to a single call... ThreadTo.

uintptr_t CPROC Thread( PTHREAD thread ) 
{
   // the ThreadTo second parameter is a uintptr_t, this may be retrieved
   // in this thread this way.
    uintptr_t myParam = GetThreadParam( thread );
    WakeableSleep( 2000 ); // wait a few seconds...
    return (uintptr_t)"Complete";
}


void f() {
  PTHREAD thread = ThreadTo( Thread, (uintptr_t)"Some Parameter" );
}

with a PTHREAD type there are additional operation..

void f() {
  PTHREAD thread = ThreadTo( Thread, (uintptr_t)"Some Parameter" );
   WakeThread( thread );  // kick it, because it fell asleep, or will soon fall asleep.
}

Get the current thread

   PTHREAD thisThread = MakeThread(); // this can be saved for later.
   // in a thread callback, MakeThread will return the same thread as the argument passed to the thread.

// this releases the thread self resources.
// this should rarely be done, when the thread exits (returns from the thread proc), this will be performed anyway.
UnmakeThread();

But some thread do a 'MakeThread()' just to check they aren't something else one time, and this can release this resource, if they no long want to support

This can terminate a thread. The thread will be terminated, and will process nothing else. Thread resources are released.

EndThread( thread );

---

##Timers

AddTimer( frequency, callback, parameter );

void CPROC Tick( uintptr_t userData ) {
    // ticks...
    // this might call RescheduleTimer( 1000 );
}


void f() {
    uint32_t timerId = AddTimer( 500, Tick, (uintptr_t)"user data" );
}

timerId can later be used in RemoveTimer or RescheduleTimer or ChangeTimer.

A more advanced version includes how long to wait the first time; which defaults otherwise to the tick value.

void f() {
    uint32_t timerId = AddTimerEx( 125, 1500, Tick, (uintptr_t)"So dangerous" );
}

so it first waits 125ms, then 1500ms every time after that. Could specify 0 as the first tick and it would run immediately and then at a tick rate after that.

// can change the conditions of a timer.
// although the initial tick is probably useless, can change the frequency of a timer
// this will change the default if no other Reschedule is done.
TIMER_PROC( void, ChangeTimerEx )( uint32_t ID, uint32_t initial, uint32_t frequency );

// reset the timer to the default frequency from now.
// this reschedule can be used to hold off a timer...
TIMER_PROC( void, RescheduleTimer )( uint32_t timer );

// if delay is 0, timer will fire immediately
// otherwise will change the time the next time the timer fires.
// does not change the default frequency.
TIMER_PROC( void, RescheduleTimerEx )( uint32_t timer, uint32_t delay );

// this stops a timer from firing again.
// if the timer is currently processing, the timer will finish and then will no longer fire.
TIMER_PROC( void, RemoveTimer )( uint32_t timer );