StructTimers system

//***************************************************************************************************
// StructTimers :
// ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
// Version     : 1.00
// Author(s)   : profet
//     
//
// DESCRIPTION:
//      This system enables the user to link a struct to a timer, it handles  timers'
//      expiration and automatically run the .End() method of the attached struct.
//
//
// HOW TO USE?
//      Each struct that uses a timer must extend  s_timer  interface, each struct must
//      include 3 methods according to following prototypes:
//      _________
//      .End() : Defines actions executed when the timer expires, also destroy the
//      ¯¯¯¯¯¯¯¯ structure's instance if it's return value is TRUE. 
//
//                  /!\ Take care to potential timer and structure leaks when
//                      returning FALSE if you don't destroy the struct by yourself.
//
//          method End takes nothing returns boolean
//              return true
//          endmethod
//
//      _______________
//      .onDestroy() : Frees the timer when the struct is destroyed.
//      ¯¯¯¯¯¯¯¯¯¯¯¯¯¯ If you are using other structs inside the struct you can
//                     destroy them here, but in most of cases you don't have to
//                     modify this method, rather put your expiration actions in
//                     .End() method.
//                     
//          method onDestroy takes nothing returns nothing
//              call StructTimers_ReleaseTimerStruct(.ti)
//          endmethod
//
//      ____________
//      .create() : Creates a struct instance, initialize the timer and custom
//      ¯¯¯¯¯¯¯¯¯¯¯ struct's variables.
//                  This method is with any doubt the less determinated of all,
//                  and the prototype below is only a frame on which you must base
//                  your own code.
//
//          static method create takes <arguments list> returns <struct.name>
//              local <struct.name> this = <struct.name>.allocate()
//              set this.ti = CreateTimer()
//              call StructTimers_StartTimedStruct( this.ti, <real:timeout>, <boolean:periodic>, this )
//              return this
//          endmethod
//
//
// EXAMPLE:
//      The following example shows how to create a timer that checks every 0.5s if
//      the unit has a specific buff, and kills it if not.
//
//      _____________________
//      Structure definition
//      ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
//          struct s_kill extends s_timer
//              private unit target
//              private integer buffid
//              private boolean explode
//              
//              method End takes nothing returns boolean
//                  if( GetUnitAbilityLevel(.target,.buffid)==0 )then
//                      call SetUnitExploded( .target, .explode )
//                      call KillUnit(.target)
//                      return true
//                  endif
//                  return false
//              endmethod
//              
//              method ChangePeriod takes real newdelay returns nothing
//                  call StructTimers_StartTimerStruct( this.ti, newdelay, true, this )
//              endmethod
//              
//              method Stop takes nothing returns nothing
//                  call .destroy()
//              endmethod
//              
//              method onDestroy takes nothing returns nothing
//                  call StructTimers_ReleaseTimerStruct(.ti)
//              endmethod
//              
//              static method create takes unit un, boolean explode, integer buffid, real delay returns s_kill
//                  local s_kill this = s_kill.allocate()
//                  //Replace following line if you're using a timers system
//                      set this.ti = CreateTimer()
//                  //end of replace
//                  set this.target = un
//                  set this.explode = explode
//                  set this.buffid = buffid
//                  call StructTimers_StartTimerStruct( this.ti, delay, true, this )
//                  return this
//              endmethod
//          endstruct
//
//      __________________________
//      Structure's usage example
//      ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
//          call s_kill.create( my_unit, false, 'BOac', 0.5 )
//
//
//
//***************************************************************************************************
library StructTimers
//===========================================================================
    globals
        private integer STRUCT_TIMERS_COUNT = 0
        private integer ASSOC_COUNT = 0
        private timer array ASSOC_TIMER
        private i_timer array ASSOC_VALUE
    endglobals
//===========================================================================
//INTERFACE DEFINITION:
//All structs using timers MUST extend the following interface:
    interface i_timer
        timer ti = null
        method End takes nothing returns boolean
    endinterface
    
//===========================================================================
//Searches for a timer in the associations-list, returns -1 if it isn't found.
    private function findTimer takes timer ti returns i_timer
    local integer i = 0
        loop
            exitwhen( i==ASSOC_COUNT )
            if( ASSOC_TIMER[i]==ti )then
                return i
            endif
            set i = i + 1
        endloop
        return -1
    endfunction

//Removes an association from the list.
    private function removeTimerAssoc takes timer ti, integer index returns nothing
        if( index<0 )then
            set index = findTimer(ti)
        endif
        if( index>-1 )then
            set ASSOC_COUNT = ASSOC_COUNT - 1
            set ASSOC_TIMER[index] = ASSOC_TIMER[ASSOC_COUNT]
            set ASSOC_VALUE[index] = ASSOC_VALUE[ASSOC_COUNT]
        endif
    endfunction

//Create an association.
    private function setTimerAssoc takes timer ti, i_timer value returns boolean
    local integer index = findTimer(ti)
        if( index==-1 and value>0 )then
            set ASSOC_TIMER[ASSOC_COUNT] = ti
            set ASSOC_VALUE[ASSOC_COUNT] = value
            set ASSOC_COUNT = ASSOC_COUNT + 1
            return true
        endif
        return false
    endfunction

//Finds and returns an association, returns 0 if no association.
    private function getTimerAssoc takes timer ti returns i_timer
    local integer index = findTimer(ti)
        if( index>-1 )then
            return ASSOC_VALUE[index]
        endif
        return 0
    endfunction

//===========================================================================
//This function is executed when a struct-timer expires. Associated .end() method
//is called, the struct is destructed if the method returns TRUE.
    private function timerExpiration takes nothing returns nothing      
    local i_timer timerstruct = getTimerAssoc( GetExpiredTimer() )
        if( timerstruct.End() )then
            call timerstruct.destroy()
        endif
    endfunction

//===========================================================================
//Similar to the usual TimerStart function, except the fact it takes a 'structid'
//argument, and does not need the <code:func> parameter.
    public function StartTimerStruct takes timer ti, real timeout, boolean periodic, integer structid returns boolean
        if( structid>0 and ti!=null and timeout>0. )then
            //Replace following line if you're using a timers system
                call TimerStart( ti, timeout, periodic, function timerExpiration )
            //end of replace
            if( setTimerAssoc( ti, structid ) )then
                set STRUCT_TIMERS_COUNT = STRUCT_TIMERS_COUNT + 1
            endif
            return true
        endif
        return false
    endfunction
    
//Removes linked association (to keep the assoc-list as small as possible).
    public function ReleaseTimerStruct takes timer ti returns nothing
        if( ti!=null )then
            //Replace following lines if you're using a timers system
                call PauseTimer(ti)
                call DestroyTimer(ti)
            //end of replace
            call removeTimerAssoc(ti,-1)
            set STRUCT_TIMERS_COUNT = STRUCT_TIMERS_COUNT - 1
        endif
    endfunction

endlibrary

struct ListElement
   ListElement next
   dataType data
endstruct