TimerQueue & Stopwatch

Author(s)
Eikonium
Tags
Lua, System
Size
6.89 KB
Rating

(1 ratings)

Downloads
57
Created
May 7, 2024
Updated
Jan 12, 2025
Resources
1
State
Approved
This bundle is marked as recommended. It works and satisfies the submission rules.
View usage Statistics Legacy download
  • Like
Reactions: maddeem, The Nightmare Book, deepstrasz and 1 other person

Overview

Documentation & Code

Changelog

TimerQueue

A resource that lets you execute delayed function calls with ease.
TimerQueue is based on a single timer no matter how many callbacks you queue at the same time. That makes it much more efficient than creating lots of separate timers.

Main Use

Lua: 
-- TimerQueue:callDelayed(delayInSeconds, function, ...)
-- will call the specified function after the specified delay with the specified arguments (...)

--print "Hello World" after 5 seconds delay
TimerQueue:callDelayed(5., print, "Hello World")
--create a footman after 3 seconds delay (i.e. 2 seconds before printing "Hello World")
TimerQueue:callDelayed(3., CreateUnit, Player(0), FourCC('hfoo'), 0, 0,0)
--It also works well with anonymous functions
TimerQueue:callDelayed(2., function() print("Hello") end)

Executing a delayed function call is really this simple - you don't need to create timers, destroy timers or define wrapper functions anymore.
A TimerQueue really shines, when you have many functions waiting for execution at the same time. That normally would require starting a lot of independent timers, while the TimerQueue handles it with a single one (which basically times the deltas in between calls), thus saving performance overhead. You can of course disregard these internals. Simply use its callDelayed-method and the TimerQueue will handle the rest.

Periodic executions

TimerQueue provides the :callPeriodically method for periodic execution:
Lua: 
-- TimerQueue:callPeriodically(delayInSeconds, stopCondition, func, ...)
-- will periodicaly call func(...), until stopCondition(...) resolves to true.

-- This example adds 10 to the gold of Player Red every two seconds, until his gold reaches 1000.
do
    ---Adds 10 to the specified player's gold.
    ---@param p player
    local function add10ToPlayerGold(p)
        AdjustPlayerStateBJ( 10, p, PLAYER_STATE_RESOURCE_GOLD )
    end
    ---Returns true, if the specified player's gold is at least 1000.
    ---@param p player
    ---@return boolean
    local function stopAt1000(p)
        return GetPlayerState(p, PLAYER_STATE_RESOURCE_GOLD) >= 1000
    end

    TimerQueue:callPeriodically(2., stopAt1000, add10ToPlayerGold, Player(0))
end

Alternatively, periodic executions can be achieved by simple recursion. As TimerQueues are based off a single timer, you don't need to worry about overhead from unnecessary timer creation.
Lua: 
function printPeriodically(x)
    print(x)
    if <condition> then TimerQueue:callDelayed(2., printPeriodically, x) end
end

printPeriodically("Hello") --prints "Hello" every 2 seconds as long as the specified condition is met.

Instantiability

The above example used :callDelayed() directly on the TimerQueue class.
That works just fine and will satisfy most use cases, but sometimes it's just more convenient to create separate TimerQueues for dfferent things:
Lua: 
tq = TimerQueue.create()
tq:callDelayed(5., print, "tq is a separate TimerQueue instance")

Creating a TimerQueue instance enables you to :pause(), :resume(), :reset() and :destroy() the instance as a whole.
Pausing a TimerQueue will pause the elapsed time for all currently queued function calls, until the TimerQueue is resumed.
Resetting a TimerQueue will discard all currently queued function calls without executing any of them.
Destroying a TimerQueue will reset it and destroy the underlying timer, which is eventually necessary to prevent memory leaks.

These methods have favorable advantages, if you want a specific set of your delayed executions to be potentially cancelable.
-> You basically call all cancel-candidates on a dedicated TimerQueue and can reset that queue at any time.
I personally need this cancelling of queued delayed functions pretty often during coding.

Imagine that you create a map centered around boss fights and the current boss is creating hostile effects on the ground, which players need to evade. These hostile effects display as red circles a few seconds before they apply, so code-wise they involve creating the circle plus a delayed function call for the actual effect. However, as soon as the boss dies, he is not supposed to cast any more abilities, even if those have already been announced by red circles, so you are required to cancel those waiting effect executions.
At the same time, players might also cast abilities involving delayed effects, which shall continue to resolve after the boss has died.

A TimerQueue can achieve that with ease: queue all boss effects into the same TimerQueue, so you can cancel all waiting executions with a single :reset().

Lua: 
--We create a dedicated TimerQueue to queue the boss abilities and another one for the player abilities
bossTQ = TimerQueue.create()
playerTQ = TimerQueue.create() --in reality, we might actually want to create a separate queue per player to be able to cancel their effects upon death individually

--As the battle progresses, more and more delayed calls are added to the queue
bossTQ:callDelayed(delay, letBossDoSomething, ...)
playerTQ:callDelayed(delay, resolveSomePlayerEffect, ...)

--Finally the boss dies and you want to cancel all executions of boss effects that are still waiting in the queue
bossTQ:reset() --discards all waiting executions from the queue. You can still add new callbacks afterwards.

--The player timerqueue is not affected and will continue to resolve all waiting executions

Disabling queued callbacks

You will normally cancel queued callbacks by resetting the underlying TimerQueue, but sometimes that's just not convenient. In that case, every queued callback can also be disabled individually, if you have the callbackId at hand that returned from your :callDelayed execution:

Lua: 
--You can save the callbackId resulting from callDelayed into a local variable
local myCallbackId = TimerQueue:callDelayed(2., function() print("Hello World") end)
--some time later
TimerQueue:disableCallback(myCallbackId) --prevents the callback from executing on timeout.

Disabling callbacks will neither pause them nor remove them from the queue. It will simply cause them to not execute on timeout (at which point they are regularly being removed from the queue without any effect).
You can use TimerQueue:enableCallback(myCallbackId) to re-enable it, if you changed your mind. This will (quite obviously) not have any effect on callbacks after timeout, even if they were disabled at that time (it's too late).

Note that TimerQueue:callPeriodically doesn't return a callbackId, so you can't disable it. This is a security measure to prevent dead periodic callbacks to sit in your TimerQueue forever. If you want to cancel or pause a periodic callback, either choose an appropriate stop-condition (and re-queue manually if desired) or create a dedicated TimerQueue that you can :reset() or :pause().

Error Handling

The TimerQueue class provides the .debugMode property, which - in case true - lets all TimerQueues print error messages upon executing erroneous function calls. This can save a lot of frustration and time, as bugs within delayed function calls are rather hard to spot and debug.
Note that the same feature is enabled by Debug Utils in case you use it. I assume you do, so TimerQueue.debugMode is set to false by default. It should be false when releasing your map to the public.

Table Recycling

All TimerQueue callbacks are internally packed into a table each. As the garbage collector in Warcraft's Lua implementation is known to cause issues when overloaded, TimerQueue recycles these tables, i.e. re-uses them where possible.
The maximum number of tables waiting for reusage at the same time is set to 128 by default, but can be adjusted in the TimerQueue code if desired. You can also set it to 0 to effectively disable table recycling.
Lua: 
--search for this line in the TimerQueue script and change the constant to one that fits your needs
local MAX_STACK_SIZE = 128

Stopwatch

A Stopwatch is a timer that counts upwards, which (surprise) you can use to stop time.
You can create a new stopwatch sw via sw = Stopwatch.create(), start it with sw:start() and receive the current elapsed time via sw:getElapsed().
As you would expect, you can also :pause(), :resume() and :destroy() a stopwatch. Please refer to the Documentation & Code tab for further information.

Installation

Create a new script in your trigger editor (above your other code) and copy the code from the Documentation & Code tab into it.

Credits

Initial credits for this resource go to @AGD. We have developed this resource together in this thread, but AGD became inactive before publishing a final version. I eventually added instantiability and here we are.


Lua: 
if Debug and Debug.beginFile then Debug.beginFile("TimerQueue") end
--[[------------------------------------------------------------------------------------------------------------------------------------------------------------
*
*    --------------------------------
*    | TimerQueue and Stopwatch 1.3 |
*    --------------------------------
*
*    - by Eikonium
*
*    -> https://www.hiveworkshop.com/threads/timerqueue-stopwatch.353718/
*    - Credits to AGD, who's "ExecuteDelayed 1.0.4" code was used as the basis for TimerQueue. See https://www.hiveworkshop.com/threads/lua-delayedaction.321072/
*
* --------------------
* | TimerQueue class |
* --------------------
*        - A TimerQueue is an object used to execute delayed function calls. It can queue any number of function calls at the same time, while being based on a single timer. This offers much better performance than starting many separate timers.
*        - The class also provides methods to pause, resume, reset and destroy a TimerQueue - and even includes error handling.
*        - As such, you can create as many independent TimerQueues as you like, which you can individually use, pause, reset, etc.
*        - All methods can also be called on the class directly, which frees you from needing to create a TimerQueue object in the first place. You still need colon-notation!
*    TimerQueue.create() --> TimerQueue
*        - Creates a new TimerQueue with its own independent timer and function queue.
*    <TimerQueue>:callDelayed(number delay, function callback, ...) --> integer (callbackId)
*        - Calls the specified function (or callable table) after the specified delay (in seconds) with the specified arguments (...). Does not delay the following lines of codes.
*        - The returned integer can usually be discarded. Saving it to a local var allows you to TimerQueue:disableCallback(callbackId) or TimerQueue:enableCallback(callbackId) later. The callbackId is unique per callback and never reused.
*    <TimerQueue>:callPeriodically(number delay, function|nil stopCondition, function callback, ...)
*        - Periodically calls the specified function (or callable table) after the specified delay (in seconds) with the specified arguments (...). Stops, when the specified condition resolves to true.
*        - The stop-condition must be a function returning a boolean. It is checked after each callback execution and is passed the same arguments as the callback (...) (which you can still ignore).
*        - You can pass nil instead of a function to let the periodic execution repeat forever.
*        - Resetting the TimerQueue will stop all periodic executions, even if the reset happened within the periodic callback.
*        - Doesn't return a callbackId, so disabling a periodic callback is only possible via either meeting the stop-condition or resetting the queue.
*    <TimerQueue>:reset()
*        - Discards all queued function calls from the Timer Queue. Discarded function calls are not executed.
*        - You can continue to use <TimerQueue>:callDelayed after resetting it.
*    <TimerQueue>:pause()
*        - Pauses the TimerQueue at its current point in time, effectively freezing all delayed function calls that it currently holds, until the queue is resumed.
*        - Using <TimerQueue>:callDelayed on a paused queue will correctly add the new callback to the queue, but time will start ticking only after resuming the queue.
*    <TimerQueue>:isPaused() --> boolean
*        - Returns true, if the TimerQueue is paused, and false otherwise.
*    <TimerQueue>:resume()
*        - Resumes a TimerQueue that was previously paused. Has no effect on TimerQueues that are not paused.
*    <TimerQueue>:destroy()
*        - Destroys the Timer Queue. Remaining function calls are discarded and not being executed.
*    <TimerQueue>:tostring() --> string
*        - Represents a TimerQueue as a list of its tasks. For debugging purposes.
*    <TimerQueue>:disableCallback(callbackId)
*        - Disables the specified callback (as per Id returned by TimerQueue:callDelayed), making it not execute upon timeout.
*        - The disabled callback will stay in the queue until timeout, allowing you to TimerQueue:enableCallback it, if you changed your mind.
*        - Use this to cancel a future callback, when resetting the whole queue is not a suitable solution.
*        - CallbackId's are unique and never reused. Using one within TimerQueue:disableCallback after original timeout will not have any effect, but you don't need to worry about accidently disabling another callback.
*    <TimerQueue>:enableCallback(callbackId)
*        - Enables the specified callback (as per Id returned by TimerQueue:callDelayed) after you have previously disabled it, making it again execute upon timeout.
*        - Enabling a callback after its timeout has already passed while disabled will not have any effect.
*    <TimerQueue>.debugMode : boolean
*        - TimerQueues come with their own error handling in case you are not using DebugUtils (https://www.hiveworkshop.com/threads/debug-utils-ingame-console-etc.330758/).
*        - Set to true to let erroneous function calls through <TimerQueue>:callDelayed print error messages on screen (only takes effect, if Debug Utils is not present. Otherwise you get Debug Utils error handling, which is even better).
*        - Set to false to not trigger error messages after erroneous callbacks. Do this before map release.
*        - Default: false (because I assume you also use DebugUtils, which provides its own error handling).
*    local MAX_STACK_SIZE : integer
*        - TimerQueue uses table recycling to unburden the garbage collector.
*        - This constant defines the maximum number of tables that can wait for reusage at the same time. Tables freed while this limit is reached will be garbage collected as normal.
*        - Can be set to 0 to disable table recycling.
*        - Default: 128. Should be fine in most scenarios. Increase, if you expect to have a lot of callbacks in the queue.
* -------------------
* | Stopwatch class |
* -------------------
*        - Stopwatches count upwards, i.e. they measure the time passed since you've started them. Thus, they can't trigger any callbacks (use normal timers or TimerQueues for that).
*    Stopwatch.create(boolean startImmediately_yn) --> Stopwatch
*        - Creates a Stopwatch. Set boolean param to true to start it immediately.
*    <Stopwatch>:start()
*        - Starts or restarts a Stopwatch, i.e. resets the elapsed time of the Stopwatch to zero and starts counting upwards.
*    <Stopwatch>:getElapsed() --> number
*        - Returns the time in seconds that a Stopwatch is currently running, i.e. the elapsed time since start.
*    <Stopwatch>:pause()
*        - Pauses a Stopwatch, so it will retain its current elapsed time, until resumed.
*    <Stopwatch>:resume()
*        - Resumes a Stopwatch after having been paused.
*    <Stopwatch>:destroy()
*        - Destroys a Stopwatch. Maybe necessary to prevent memory leaks. Not sure, if lua garbage collection also collects warcraft objects...
---------------------------------------------------------------------------------------------------------------------------------------------------------]]

do

    --Help data structures for recycling tables for tasks (TimerQueueElements) in TimerQueues.
    local recycleStack = {} --Used tables are stored here to prevent garbage collection, up to MAX_STACK_SIZE
    local stackSize = 0 --Current number of tables stored in recycleStack
    local MAX_STACK_SIZE = 128 --Max number of tables that can be stored in recycleStack. Set this to a value > 0 to activate table recycling.

    ---@class TimerQueueElement
    ---@field [integer] any arguments to be passed to callback
    TimerQueueElement = {
        next = nil                      ---@type TimerQueueElement next TimerQueueElement to expire after this one
        ,   timeout = 0.                ---@type number time between previous callback and this one
        ,   callback = function() end   ---@type function callback to be executed
        ,   n = 0                       ---@type integer number of arguments passed
        ,   enabled = true              ---@type boolean defines whether the callback shall be executed on timeout or not.
        ,   id = 0                      ---@type integer unique id of this TimerQueueElement
        --static
        ,   nextId = 0                  ---@type integer ever increasing counter that shows the unique id of the next TimerQueueElement being created.
        ,   storage = setmetatable({}, {__mode = 'v'})                ---@type table<integer, TimerQueueElement> saves all TimerQueueElements by their unique id. Weak values to not interfere with garbage collection.
    }
    TimerQueueElement.__index = TimerQueueElement
    TimerQueueElement.__name = 'TimerQueueElement'

    local fillTable
    ---Recursive help function that fills a table with the specified arguments from index to maxIndex.
    ---@param whichTable table table to be filled
    ---@param index integer current index to be filled with firstParam
    ---@param maxIndex integer maximum index up to which to continue recursively
    ---@param firstParam any first param is mentioned explicitly to simplify the recursive call below
    ---@param ... any second and subsequent params
    fillTable = function(whichTable, index, maxIndex, firstParam, ...)
        whichTable[index] = firstParam
        if index < maxIndex then
            fillTable(whichTable, index + 1, maxIndex, ...)
        end
    end

    ---Creates a new TimerQueueElement, which points to itself.
    ---@param timeout? number
    ---@param callback? function
    ---@param ... any arguments for callback
    ---@return TimerQueueElement
    function TimerQueueElement.create(timeout, callback, ...)
        local new
        if stackSize == 0 then
            new = setmetatable({timeout = timeout, callback = callback, id = TimerQueueElement.nextId, n = select('#', ...), ...}, TimerQueueElement)
        else
            new = setmetatable(recycleStack[stackSize], TimerQueueElement)
            recycleStack[stackSize] = nil
            stackSize = stackSize - 1
            new.timeout, new.callback, new.id, new.n = timeout, callback, TimerQueueElement.nextId, select('#', ...)
            fillTable(new, 1, new.n, ...) --recursive fillTable is around 20 percent faster than a for-loop based on new[i] = select(i, ...)
        end
        new.next = new
        TimerQueueElement.nextId = TimerQueueElement.nextId + 1
        TimerQueueElement.storage[new.id] = new
        return new
    end

    ---Empties a TimerQueueElement and puts it to the recycleStack.
    ---@param timerQueueElement TimerQueueElement
    local function recycleTimerQueueElement(timerQueueElement)
        --remove TimerQueueElement from storage and remove metatable
        TimerQueueElement.storage[timerQueueElement.id] = nil
        setmetatable(timerQueueElement, nil)
        --If table recycling is activated and there is space on the recycleStack, push the TimerQueueElement back onto it.
        if stackSize < MAX_STACK_SIZE then
            --empty table before putting it back
            for i = 1, timerQueueElement.n do
                timerQueueElement[i] = nil
            end
            timerQueueElement.next, timerQueueElement.callback, timerQueueElement.n, timerQueueElement.timeout, timerQueueElement.enabled, timerQueueElement.id = nil, nil, nil, nil, nil, nil
            --push on stack
            stackSize = stackSize + 1
            recycleStack[stackSize] = timerQueueElement
        end
        --Else: Do nothing. TimerQueueElement will automatically be garbage collected.
    end

    ---@class TimerQueue
    TimerQueue = {
        timer = nil                     ---@type timer the single timer this system is based on (one per instance of course)
        ,   queue = TimerQueueElement.create() -- queue of waiting callbacks to be executed in the future
        ,   n = 0                       ---@type integer number of elements in the queue
        ,   on_expire = function() end  ---@type function callback to be executed upon timer expiration (defined further below).
        ,   debugMode = false           ---@type boolean setting this to true will print error messages, when the input function couldn't be executed properly. Set this to false before releasing your map.
        ,   paused = false              ---@type boolean whether the queue is paused or not
    }

    TimerQueue.__index = TimerQueue
    TimerQueue.__name = 'TimerQueue'

    --Creates a timer on first access of the static TimerQueue:callDelayed method. Avoids timer creation inside the Lua root.
    setmetatable(TimerQueue, {__index = function(t,k) if k == 'timer' then t[k] = CreateTimer() end; return rawget(t,k) end})

    local unpack, max, timerStart, timerGetElapsed, pauseTimer, try = table.unpack, math.max, TimerStart, TimerGetElapsed, PauseTimer, Debug and Debug.try

    ---@param timerQueue TimerQueue
    local function on_expire(timerQueue)
        local queue, timer = timerQueue.queue, timerQueue.timer
        local topOfQueue = queue.next
        queue.next = topOfQueue.next
        timerQueue.n = timerQueue.n - 1
        if timerQueue.n > 0 then
            timerStart(timer, queue.next.timeout, false, timerQueue.on_expire)
        else
            -- These two functions below may not be necessary
            timerStart(timer, 0, false, nil) --don't put in on_expire as handlerFunc, because it can still expire and reduce n to a value < 0.
            pauseTimer(timer)
        end
        if topOfQueue.enabled then
            if try then
                try(topOfQueue.callback, unpack(topOfQueue, 1, topOfQueue.n))
            else
                local errorStatus, errorMessage = pcall(topOfQueue.callback, unpack(topOfQueue, 1, topOfQueue.n))
                if timerQueue.debugMode and not errorStatus then
                    print("|cffff5555ERROR during TimerQueue callback: " .. errorMessage .. "|r")
                end
            end
        end
        recycleTimerQueueElement(topOfQueue)
    end

    TimerQueue.on_expire = function() on_expire(TimerQueue) end

    ---@return TimerQueue
    function TimerQueue.create()
        local new = {}
        setmetatable(new, TimerQueue)
        new.timer = CreateTimer()
        new.queue = TimerQueueElement.create()
        new.on_expire = function() on_expire(new) end
        return new
    end

    ---Calls a function (or callable table) after the specified timeout (in seconds) with all specified arguments (...). Does not delay the following lines of codes.
    ---@param timeout number
    ---@param callback function|table if table, must be callable
    ---@param ... any arguments of the callback function
    ---@return integer callbackId usually discarded. Can be saved to local var to use in :disableCallback() or :enableCallback() later.
    function TimerQueue:callDelayed(timeout, callback, ...)
        timeout = math.max(timeout, 0.)
        local queue = self.queue
        self.n = self.n + 1
        -- Sort timeouts in descending order
        local current = queue
        local current_timeout = current.next.timeout - max(timerGetElapsed(self.timer), 0.) -- don't use TimerGetRemaining to prevent bugs for expired and previously paused timers.
        while current.next ~= queue and timeout >= current_timeout do --there is another element in the queue and the new element shall be executed later than the current
            timeout = timeout - current_timeout
            current = current.next
            current_timeout = current.next.timeout
        end
        -- after loop, current is the element that executes right before the new callback. If the new is the front of the queue, current is the root element (queue).
        local new = TimerQueueElement.create(timeout, callback, ...)
        new.next = current.next
        current.next = new
        -- if the new callback is the next to expire, restart timer with new timeout
        if current == queue then --New callback is the next to expire
            new.next.timeout = max(current_timeout - timeout, 0.) --adapt element that was previously on top. Subtract new timeout and subtract timer elapsed time to get new timeout.
            timerStart(self.timer, timeout, false, self.on_expire)
            if self.paused then
                self:pause()
            end
        else
            new.next.timeout = max(new.next.timeout - timeout, 0.) --current.next might be the root element (queue), so prevent that from dropping below 0. (although it doesn't really matter)
        end
        return new.id
    end

    ---Calls the specified callback with the specified argumets (...) every <timeout> seconds, until the specified stop-condition holds.
    ---The stop-condition must be a function returning a boolean. It is checked after every callback execution. All arguments (...) are also passed to the stop-conditon (you can still ignore them).
    ---Resetting the TimerQueue will stop all periodic executions, even if the reset happened within the periodic callback.
    ---Doesn't return a TimerQueue-Element, so disabling is only possible by either meeting the stop-condition or resetting the queue.
    ---@param timeout number time between calls
    ---@param stopCondition? fun(...):boolean callback will stop to repeat, when this condition holds. You can pass nil to skip the condition (i.e. the periodic execution will run forever).
    ---@param callback fun(...) the callback to be executed
    ---@param ... any arguments for the callback
    function TimerQueue:callPeriodically(timeout, stopCondition, callback, ...)
        local func
        func = function(...)
            local queue = self.queue --memorize queue element to check later, whether TimerQueue:reset has been called in the meantime.
            callback(...) --execute callback first
            --re-queue, if stopCondition doesn't hold and the TimerQueue has not been reset during the callback (checked via queue == self.queue)
            if queue == self.queue and not (stopCondition and stopCondition(...)) then
                self:callDelayed(timeout, func, ...)
            end
        end
        self:callDelayed(timeout, func, ...)
    end

    ---Recycles all elements of a given TimerQueue, up to the limit given by MAX_STACK_SIZE
    ---@param timerQueue TimerQueue
    local function recycleQueueElements(timerQueue)
        --Recycle all TimerQueueElements in the queue, but not the root element (which is used for call-by-reference checks in :callPeriodically)
        local current, next = timerQueue.queue.next, nil
        while current ~= timerQueue.queue and stackSize < MAX_STACK_SIZE do --stop recycling early, if MAX_STACK_SIZE is reached. Remaining TimerQueueElements will be garbage collected. Weak values in TimerQueueElement.storage makes sure no reference is left.
            next = current.next --need to save current.next here, as it gets nilled during recycleTimerQueueElement
            recycleTimerQueueElement(current)
            current = next
        end
        TimerQueueElement.storage[timerQueue.queue.id] = nil
    end

    ---Removes all queued calls from the Timer Queue, so any remaining actions will not be executed.
    ---Using <TimerQueue>:callDelayed afterwards will still work.
    function TimerQueue:reset()
        recycleQueueElements(self)
        --Reset timer and create new queue to replace the old
        timerStart(self.timer, 0., false, nil) --don't put in on_expire as handlerFunc. callback can still expire after pausing and resuming the empty queue, which would set n to a value < 0.
        pauseTimer(self.timer)
        self.n = 0
        self.queue = TimerQueueElement.create()
    end

    ---Pauses the TimerQueue at its current point in time, preventing all queued callbacks from being executed, until the queue is resumed.
    ---Using <TimerQueue>:callDelayed on a paused queue will correctly add the new callback to the queue, but time will start ticking only after the queue is being resumed.
    function TimerQueue:pause()
        self.paused = true
        pauseTimer(self.timer)
    end

    ---Returns true, if the timer queue is paused, and false otherwise.
    ---@return boolean
    function TimerQueue:isPaused()
        return self.paused
    end

    ---Resumes a TimerQueue that was paused previously. Has no effect on running TimerQueues.
    function TimerQueue:resume()
        if self.paused then
            self.paused = false
            self.queue.next.timeout = self.queue.next.timeout - timerGetElapsed(self.timer) --need to restart from 0, because TimerGetElapsed(resumedTimer) is doing so as well after a timer is resumed.
            ResumeTimer(self.timer)
        end
    end

    ---Destroys the timer object behind the TimerQueue. The Lua object will be automatically garbage collected once you ensure that there is no more reference to it.
    function TimerQueue:destroy()
        pauseTimer(self.timer) --https://www.hiveworkshop.com/threads/issues-with-timer-functions.309433/ suggests that non-paused destroyed timers can still execute their callback
        DestroyTimer(self.timer)
        recycleQueueElements(self)
        self.queue = nil
        setmetatable(self, nil) --prevents consequences on the TimerQueue class, if further methods (like :destroy again) are used on the destroyed TimerQueue.
    end

    ---Returns a list of queued callbacks within the TimerQueue. For debugging purposes.
    ---@return string
    function TimerQueue:tostring()
        local current, result, i = self.queue.next, {}, 0
        local args = {}
        while current ~= self.queue do
            i = i + 1
            for j = 1, current.n do
                args[j] = tostring(current[j])
            end
            result[i] = '(i=' .. i .. ',timeout=' .. current.timeout .. ',enabled = ' .. tostring(current.enabled) .. ',f=' .. tostring(current.callback) .. ',args={' .. table.concat(args, ',',1,current.n) .. '})'
            current = current.next
        end
        return '{n = ' .. self.n .. ',queue=(' .. table.concat(result, ',', 1, i) .. ')}'
    end

    ---Disables a callback that is currently queued in the TimerQueue.
    ---The callback will still sit in the queue until timeout, but resolve without any effect.
    ---This method is similiar to resetting the whole TimerQueue, just limited to a single callback.
    ---@param callbackId integer the callbackId returned by TimerQueue:callDelayed
    function TimerQueue:disableCallback(callbackId)
        if TimerQueueElement.storage[callbackId] then
            TimerQueueElement.storage[callbackId].enabled = false
        end
    end

    ---Re-enables a callback that was previously disabled by TimerQueue:disableCallback.
    ---@param callbackId integer the callbackId returned by TimerQueue:callDelayed
    function TimerQueue:enableCallback(callbackId)
        if TimerQueueElement.storage[callbackId] then
            TimerQueueElement.storage[callbackId].enabled = true
        end
    end

    ---@class Stopwatch
    Stopwatch = {
        timer = {}                                  ---@type timer the countdown-timer permanently cycling
        ,   elapsed = 0.                            ---@type number the number of times the timer reached 0 and restarted
        ,   increaseElapsed = function() end        ---@type function timer callback function to increase numCycles by 1 for a specific Stopwatch.
    }
    Stopwatch.__index = Stopwatch

    local CYCLE_LENGTH = 3600. --time in seconds that a timer needs for one cycle. doesn't really matter.

    ---Creates a Stopwatch.
    ---@param startImmediately_yn boolean Set to true to start immediately. If not specified or set to false, the Stopwatch will not start to count upwards.
    function Stopwatch.create(startImmediately_yn)
        local new = {}
        setmetatable(new, Stopwatch)
        new.timer = CreateTimer()
        new.elapsed = 0.
        new.increaseElapsed = function() new.elapsed = new.elapsed + CYCLE_LENGTH end
        if startImmediately_yn then
            new:start()
        end
        return new
    end

    ---Starts or restarts a Stopwatch, i.e. resets the elapsed time of the Stopwatch to zero and starts counting upwards.
    function Stopwatch:start()
        self.elapsed = 0.
        TimerStart(self.timer, CYCLE_LENGTH, true, self.increaseElapsed)
    end

    ---Returns the time in seconds that a Stopwatch is currently running, i.e. the elapsed time since start.
    ---@return number
    function Stopwatch:getElapsed()
        return self.elapsed + TimerGetElapsed(self.timer)
    end

    ---Pauses a Stopwatch, so it will retain its current elapsed time, until resumed.
    function Stopwatch:pause()
        PauseTimer(self.timer)
    end

    ---Resumes a Stopwatch after having been paused.
    function Stopwatch:resume()
        self.elapsed = self.elapsed + TimerGetElapsed(self.timer)
        TimerStart(self.timer, CYCLE_LENGTH, true, self.increaseElapsed) --not using ResumeTimer here, as it actually starts timer from new with the remaining time and thus screws up TimerGetElapsed().
    end

    ---Destroys the timer object behind the Stopwatch. The Lua object will be automatically garbage collected once you ensure that there is no more reference to it.
    function Stopwatch:destroy()
        DestroyTimer(self.timer)
    end
end
if Debug and Debug.endFile then Debug.endFile() end

30.4.2022, v1.0 (Initial Release):
  • TimerQueue as an instancifiable version of [Lua] - DelayedAction
  • Added :pause(), :resume(), :reset(), :destroy() and error handling for erroneous callbacks.
  • Added Stopwatch functionality

01.05.2023, v1.1:
  • Switched from array-based to linked-list-based queue to improve performance of TimerQueue:callDelayed.
  • Switched from absolute timestamps to relative timestamps to drastically improve performance of TimerQueue:pause().
  • Integrated the newest version of Debug Utils for better error messages and local file references in particular.
  • Optimized script to prevent unnecessary table creation.
  • Added TimerQueue:printPeriodically(timeout, stopCondition, callback, ...), :isPaused() and TimerQueue:tostring().
  • Fixed a bug, where using :callDelayed on a paused empty TimerQueue would unintentionally resume the Queue. Thanks to @Insanity_AI for reporting this.
12.08.2024, v1.2:
  • Added methods :disable() and :enable() for TimerQueueElements. Thanks @maddeem for the suggestion.
  • Resetting a TimerQueue inside a periodic callback will now prevent the callback from re-queueing after the reset, as requested by @Insanity_AI.
23.12.2024, v1.3:

⚠️This version of TimerQueue deprecates the methods TimerQueueElement:disable() and TimerQueueElement:enable() introduced in version 1.2 and replaces them by TimerQueue:disableCallback(callbackId) and TimerQueue:enableCallback(callbackId). If switching is too troublesome, simply stay on the previous version.

Lua: 
--Deprecated:
local myTimerQueueElement = TimerQueue:callDelayed(...)
myTimerQueueElement:disable()

--Way to go for version 1.3 onwards:
local myCallbackId = TimerQueue:callDelayed(...)
TimerQueue:disableCallback(myCallbackId)
  • Added table recycling to unburden the garbage collector, as suggested by @Wrda, @maddeem and @Insanity_AI. TimerQueue's table use is currently one per callback. You can adjust the number of free tables waiting for reusage at the same time by setting local MAX_STACK_SIZE = <yourInteger> --default 128 in the map script.
  • Deprecated TimerQueueElement:disable() and TimerQueueElement:enable() and replaced them by TimerQueue:disableCallback(callbackId) and TimerQueue:enableCallback(callbackId).

Contents

TimerQueue & Stopwatch (Binary)

Size
6.89 KB
Uploaded
May 7, 2024
Updated
Dec 23, 2024
Download
Reviews
Antares
Antares
Originally approved by @Bribe : "I see no reason why this should sit in the Submissions forum any longer. This is yet another high-quality resource of yours that is each instructive, functional, beautifully-designed and serves a unique purpose."...
Read full review...

Antares

Antares

Antares

Spell Reviewer
Level 32
Joined
Dec 13, 2009
Messages
982
Originally approved by @Bribe :

"I see no reason why this should sit in the Submissions forum any longer. This is yet another high-quality resource of yours that is each instructive, functional, beautifully-designed and serves a unique purpose."

And, if I may add, this is how a documentation should be written! Beautiful! ❤️

Approved
 
Last edited:

Eikonium

Eikonium

Eikonium

Patron
Level 23
Joined
Jul 10, 2009
Messages
534
Wrda said:
The left script (version 1.1) is the one on the main post of [Lua] - TimerQueue & Stopwatch, which is 99.9% identical to the Insanity_AI's fix. The right script (1.0) looks like the initial version.
This is Back to The Past, I guess? 😁
Click to expand...
Isn't the code from this page exactly the one from your left screenshot? :)
 

Insanity_AI

Insanity_AI

Insanity_AI

Level 7
Joined
Jun 30, 2017
Messages
50
Greetings, I bring forth another bug report:

Consider the following code:

Lua: 
if Debug then Debug.beginFile "Example" end
OnInit.final(function(require)
    require "TimerQueue"

    -- Granted, this all could have been done smarter, but this is just the bug showcase

    local timer = TimerQueue.create()

    local isRunning = false
    local tick = 0

    local function onInterval()
        print "Tick"
        tick = tick + 1

        if tick >= 20 then
            print "End ticking"
            tick = 0
            timer:reset()
            isRunning = false
        end
    end

    function StartTicking()
        if not isRunning then
            isRunning = true
            timer:callPeriodically(0.03, nil, onInterval)
        end
    end

end)
if Debug then Debug.endFile() end

What was expected to happen:
- only one onInterval function being executed for the 20 ticks regardless of how many StartTicking calls happen

What actually happens:
  • after the first StartTicking call has ticked out (tick >= 20), and doing a second call, it appears that the entire thing starts ticking twice as fast.
  • EDIT: actually, I think this example would print "End ticking" but it wouldn't stop, just keep going from 0 to 20 over and over again with just 1 StartTicking call

Reason:
- timer:reset does not clear out the queue like you expect it, and the cause is actually with timer:callPeriodically


Lua: 
    function TimerQueue:callPeriodically(timeout, stopCondition, callback, ...)
        local func
        func = function(...)
            callback(...)
            if not (stopCondition and stopCondition(...)) then
            --->    self:callDelayed(timeout, func, ...)   <---
            end
        end
        self:callDelayed(timeout, func, ...)
    end
If the reset is called in callback, it does not encompass the upcoming callDelayed call that happens in this case, making it so that the timer will always have at least 1 periodic function despite the amount of times the reset is called in that periodic callback function
 
Last edited:

Eikonium

Eikonium

Eikonium

Patron
Level 23
Joined
Jul 10, 2009
Messages
534
Insanity_AI said:
Greetings, I bring forth another bug report:
Click to expand...
This is a tough one. From my point of view, this is working as intended, but I totally understand that the behaviour is not intuitive and should maybe be improved.

Why I think it's working as intended:
  • TimerQueue:callPeriodically is supposed to re-queue the callback after every execution in case the stop-condition is not met.
  • You are resetting during callback execution, which doesn't prevent re-queuing afterwards.
  • Documentation states that the stop-condition (implying the re-queuing) is evaluated after the callback has been executed.
Still your issue holds. It's not intuitive to keep the active periodic callback in the queue, when all others are discarded. And I can't expect users to have knowledge about re-queuing behaviour of :callDelayed.
I will work on an update :)
 

Eikonium

Eikonium

Eikonium

Patron
Level 23
Joined
Jul 10, 2009
Messages
534
Update to version 1.2:
  • Added methods :disable() and :enable() for TimerQueueElements.
    This allows you to disable a single callback instead of resetting the whole queue:
    Lua: 
    --You can save the TimerQueueElement resulting from callDelayed into a local variable
local someTQElement = TimerQueue:callDelayed(2., function() print("Hello World") end) ---@type TimerQueueElement
--1s later
someTQElement:disable() --prevents the callback from executing on timeout.
    Disabling a TimerQueueElement will not remove it from the queue, but just skip callback execution on timeout (same result).
    Thanks @maddeem for the suggestion.
  • Resetting a TimerQueue inside a periodic callback will now prevent the callback from re-queueing after the reset, as requested by @Insanity_AI.
 

maddeem

maddeem

maddeem

Level 24
Joined
Jan 1, 2011
Messages
1,534
I want to preface my review by saying I have slightly altered an older version of this to make use of table recycling.

Okay so the way this system allows you to seamlessly queue delayed functions with whatever arguments you want is just supremely powerful. Before using this I was always at least a bit hesitant to introduce timers into a code snippet because of how unwieldy they are.

Using this has caused a total paradigm shift for me and how I approach problems. I'm adding delays everywhere, especially for sound design or animation. Then as if it can't get better you can run all of your game logic through one timer and pause it to effectively pause the game.

I have seriously battle tested this system with many thousands of callbacks in the queue and it performs like a champion. Thank you for making this, it has really opened my eyes to making better tooling for better development.
 

Eikonium

Eikonium

Eikonium

Patron
Level 23
Joined
Jul 10, 2009
Messages
534
Christmas update 🎅 v1.3:
  • Added table recycling to unburden the garbage collector, as suggested by @Wrda, @maddeem and @Insanity_AI. TimerQueue's table use is currently one per callback. You can adjust the number of free tables waiting for reusage at the same time by setting local MAX_STACK_SIZE = <yourInteger> --default 128 in the map script.
  • Deprecated TimerQueueElement:disable() and TimerQueueElement:enable() and replaced them by TimerQueue:disableCallback(callbackId) and TimerQueue:enableCallback(callbackId).

⚠️
This version of TimerQueue deprecates the methods TimerQueueElement:disable() and TimerQueueElement:enable() introduced in version 1.2 and replaces them by TimerQueue:disableCallback(callbackId) and TimerQueue:enableCallback(callbackId). If switching is too troublesome, simply stay on the previous version.

Lua: 
--Deprecated:
local myTimerQueueElement = TimerQueue:callDelayed(...)
myTimerQueueElement:disable()

--Way to go for version 1.3 onwards:
local myCallbackId = TimerQueue:callDelayed(...)
TimerQueue:disableCallback(myCallbackId)
 
You must log in or register to reply here.

Similar threads

Eikonium
[Lua] TimerQueue & Stopwatch
Replies
20
Views
4K
Eikonium
Eikonium
Inferior
  • Locked
[JASS] Why don't the natives work
Replies
4
Views
2K
Inferior
Inferior
Nestharus
[System] TimerQueue
Replies
23
Views
4K
Bribe
Bribe
The Reborn Devil
  • Locked
Hive's Essential Tools
Replies
14
Views
2K
The Reborn Devil
The Reborn Devil
TriggerHappy
  • Locked
StopWatch API - Benchmarking for Everyone
Replies
6
Views
3K
TriggerHappy
TriggerHappy
Top