PeriodicLoop

//! zinc
library PeriodicLoop requires optional xebasic {
/**
 *      The main purpose of PeriodicLoop is to provide the user with a module that implements a fully optimized
 *   periodic loop for a struct. Instances that are added to the loop are stored in a doubly linked list, which improves
 *   the loop's efficiency and allows the removal to be just as easy as the insertion. The user is also provided with
 *   internal wrappers that are meant to be used when dealing with static functions, as opposed to the regular, non-static
 *   methods. These wrappers are implemented with the help of a dummy struct and function pointers.
 *
 *      Note that this script was written solely for high-frequency loops, and is by default configured to loop 40 times per
 *   second. You can change this interval by editing PERIODIC_LOOP_INTERVAL constant found right below the documentation.
 *   That constant is also public, and as such should be used with all "over time" effects in order to ensure consistency,
 *   accuracy and portability. Neither multiple intervals nor dynamic adjustments in the interval are supported.
 *
 *      If the xebasic library is present within the map, then the XE_ANIMATION_PERIOD constant will be used instead of
 *   PERIODIC_LOOP_INTERVAL. Please, do not set these constants to anything higher than 0.05, as that would result in lots
 *   of stuff being inaccurate and bumpy. The most commonly used values are 0.025 and 0.03125.
 *   
 *   Now, let's elaborate on the implementation of the script. As I mentioned earlier, you can utilize two "types" of API:
 *
 *      - For the regular, module-based API, the following things need to be done:
 *   
 *   1) Implement the "PeriodicLoop" module within your struct.
 *   2) Declare a non-static method named "onPeriodicLoop". That particular method will be called every interval
 *      as long as there are nodes on the looping list.
 *   3) When you're willing to add a node, simply call structInstance.startPeriodicLoop(), and when you're willing
 *      to remove it, call structInstance.stopPeriodicLoop().
 *   4) Make sure that the module is implemented above all .startPeriodicLoop() calls and below the 
 *      "onPeriodicLoop" method in order to avoid unnecessary trigger evaluations. This is very important.
 *   5) Do not leave destroyed instances in the loop - always call .stopPeriodicLoop() before calling .destroy() or
 *      .deallocate().
 *
 *      - Registering static functions is even easier. The API is the following:
 *      
 *   1) RegisterPeriodicResponse takes response whichResponse returns nothing
 *   2) UnregisterPeriodicResponse takes response whichResponse returns nothing
 *   
 *      In the above two functions, "response" is a function pointer (you can see its definition below), so "whichResponse"
 *   is the name of a function or a static method that takes and returns nothing. Akin to the "onPeriodicLoop" method, the
 *   passed response will be called every interval until UnregisterPeriodicResponse(response) is called.
 */
    public constant real PERIODIC_LOOP_INTERVAL = 1.0/40.0;
    
    type response extends function();

    private
    {
        trigger mainTrigger = CreateTrigger(); // The trigger onto which the iterators will be attached.
        timer mainTimer = CreateTimer(); // This timer will be used to periodically evaluate the above trigger.
        integer that = 0, globalCount = 0; // The former will be used to temporarily store a node, while the
    }                                      // latter will be used to keep count of the running instances.

    public module PeriodicLoop
    {
        private // Module-private members.
        {
            thistype next, previous; // These, along with the null struct, will help us build the doubly linked list.
            boolean alreadyInserted, pendingRemoval; // Self-explanatory, I hope.
            static triggercondition instanceIterator = null; // We will use this variable to store the struct's iterator.
            static boolean threadCrashed = false; // In debug mode, this boolean will help us catch and report thread crashes.
        }
        
        private static method iterator() -> boolean
        {
            thistype this = thistype(0).next; // Get the first node.
            
            debug
            {
                if (thistype.threadCrashed) // Warn the user if the thread had crashed during the last loop.
                {
                    BJDebugMsg("PeriodicLoop warning: The thread had crashed during the last loop!\n" +
                    "Make sure you are not performing very intensive operations or using uninitialized variables!\n" +
                    "The name of the iterator in which the thread crashed is \"" + thistype.iterator.name + "\"");
                }
                thistype.threadCrashed = true;
            }
            
            while (integer(this) != 0) // Traverse the list.
            {
                if (this.pendingRemoval) // See if the current node should be removed.
                {
                    this.pendingRemoval = false;

                    // Remove the node.
                    this.previous.next = this.next;
                    this.next.previous = this.previous;
                    
                    if (this.alreadyInserted) // See if the node should be reinserted.
                    {
                        that = integer(this.next); // Temporarily store the next node.
                        
                        // Reinsert it at the end of the list.
                        thistype(0).previous.next = this;
                        this.previous = thistype(0).previous;
                        thistype(0).previous = this;
                        this.next = thistype(0);
                        
                        if (thistype(that) == thistype(0)) // If the next node was in fact null,
                            this = thistype(0).previous;   // then go back to the previous one.
                        else 
                            this = thistype(that); // Otherwise, go to the next node normally.
                    }
                    else
                    {
                        globalCount -= 1; // Decrement the global count.
                        
                        if (globalCount == 0) // Check whether the timer should keep running.
                            PauseTimer(mainTimer);
                            
                        if (thistype(0).next == thistype(0)) // Check if the iterator should be detached from the trigger.
                            TriggerRemoveCondition(mainTrigger, thistype.instanceIterator);

                        this = this.next; // Go to the next node.
                    }
                }
                else
                {
                    this.onPeriodicLoop(); // Call the .onPeriodicLoop() method.
                    this = this.next; // Go to the next node.
                }
            }

            debug thistype.threadCrashed = false; // If we made it here, then the thread hasn't crashed.

            return false;
        }

        method startPeriodicLoop() 
        {
            if (!this.alreadyInserted && integer(this) > 0) // Make sure the method was called on a valid node.
            {
                this.alreadyInserted = true;
                
                if (!this.pendingRemoval) // First, see if the node was flagged for removal.
                {
                    // And if it wasn't, insert it at the end of the linked list.
                    thistype(0).previous.next = this;
                    this.previous = thistype(0).previous;
                    thistype(0).previous = this;
                    this.next = thistype(0);
                
                    globalCount += 1; // Increment the global count.
                    
                    if (globalCount == 1) // Check if the timer should be started (or resumed).
                        static if (LIBRARY_xebasic)
                            TimerStart(mainTimer, XE_ANIMATION_PERIOD, true, static method() { TriggerEvaluate(mainTrigger); });
                        else
                            TimerStart(mainTimer, PERIODIC_LOOP_INTERVAL, true, static method() { TriggerEvaluate(mainTrigger); });

                    if (this.previous == thistype(0)) // Check if the iterator should be (re)attached to the trigger.
                        thistype.instanceIterator = TriggerAddCondition(mainTrigger, Condition(static method thistype.iterator));
                }
            }
        }

        method stopPeriodicLoop()
        {
            if (this.alreadyInserted && integer(this) > 0) // Make sure the method was called on a valid node.
            {
                this.pendingRemoval = true; // Flag this node so that it would be removed during the next loop.
                this.alreadyInserted = false;
            }
        }
    }

    private struct staticFunctionHelper[] // This is just a dummy struct.
    {
        method onPeriodicLoop()
        {
            response(integer(this)).evaluate();
        }
        module PeriodicLoop;
    }
    
    public // Below is the API for dealing with static responses.
    {
        function RegisterPeriodicResponse(response whichResponse)
        {
            staticFunctionHelper(integer(whichResponse)).startPeriodicLoop();
        }
        
        function UnregisterPeriodicResponse(response whichResponse)
        {
            staticFunctionHelper(integer(whichResponse)).stopPeriodicLoop();
        }
    }
}
//! endzinc

struct periodicLoopExample
          
    integer count = 1
    real customValue

    private static method print takes string message returns nothing
        call DisplayTimedTextToPlayer(GetLocalPlayer(), 0.0, 0.0, 10.0, message)
    endmethod
 
    private method onPeriodicLoop takes nothing returns nothing
        call .print("Struct #" + I2S(integer(this)) + " has looped for the " + I2S(.count) + ". time!")
        call .print("customValue = " + R2S(.customValue))
        call .print("-------------------------------------------------------")
        
        set .count = .count + 1
       
        if (.count > (5 / PERIODIC_LOOP_INTERVAL)) then
            call .stopPeriodicLoop()
            call .destroy()
        endif
    endmethod
 
    implement PeriodicLoop
 
    private static method onInit takes nothing returns nothing
        local thistype this = thistype.create()
        set .customValue = 3.14159
        call .startPeriodicLoop()
        set this = thistype.create()
        set .customValue = 2.71828
        call .startPeriodicLoop()
        set this = thistype.create()
        set .customValue = 1.61803
        call this.startPeriodicLoop()
    endmethod

endstruct

scope periodicLoopExample initializer onInit
    
    globals
        private unit footman = null
        private integer count = 0
    endglobals
    
    private function degeneration takes nothing returns nothing
        call SetWidgetLife(footman, GetWidgetLife(footman) - (20 * PERIODIC_LOOP_INTERVAL))
        set count = count + 1
        if (count == (15 / PERIODIC_LOOP_INTERVAL)) then
            call UnregisterPeriodicResponse(degeneration)
        endif
    endfunction

    private function onInit takes nothing returns nothing
        set footman = CreateUnit(Player(0), 'hfoo', 0.0, 0.0, 0.0)
        call RegisterPeriodicResponse(degeneration)
    endfunction

endscope

        method startLooping() 
        {
            if (!this.alreadyAdded && integer(this) > 0) // Make sure the method was called on a valid node.
            {
                this.alreadyAdded = true; //Set the already added flag first.
                if (this.pendingRemoval) // First, see if the node was flagged for removal.
                {
                    // Do nothing here, the periodic loop will handle everything.
                }
                else
                {
                    // And if it wasn't, insert it at the end of the linked list.
                    thistype(0).previous.next = this;
                    this.previous = thistype(0).previous;
                    thistype(0).previous = this;
                    this.next = thistype(0);
                    globalCount += 1; // Increment the global count.
                
                    if (globalCount == 1) // Check if the timer should be started (or resumed).
                        TimerStart(mainTimer, LOOP_INTERVAL, true, static method() { TriggerEvaluate(mainTrigger); });
                
                    if (this.previous == thistype(0)) // Check if this is first node on the list.
                    {
                        // Attach the iterator to the trigger.
                        // Not sure if using an anonymous function here is very conductive to code readability.
                        thistype.instanceIterator = TriggerAddCondition(mainTrigger, static method() -> boolean
                        {
                            thistype this = thistype(0).next;
                            while (integer(this) != 0) // Traverse the list.
                            {
                                if (this.pendingRemoval) // See if the instance should be removed.
                                {
                                    // Remove the node from the linked list.
                                    this.previous.next = this.next;
                                    this.next.previous = this.previous;
                                
                                    this.pendingRemoval = false;
                                    if (this.alreadyAdded) // See if the instance should be readded.
                                    {
                                        // Readd it if needed.
                                        thistype(0).previous.next = this;
                                        this.previous = thistype(0).previous;
                                        thistype(0).previous = this;
                                        this.next = thistype(0);
                                    }
                                    else
                                    {
                                        globalCount -= 1; // Decrement the global count.

                                        if (globalCount == 0) // Check whether the timer should keep running.
                                            PauseTimer(mainTimer);

                                        if (thistype(0).next == thistype(0)) // Check if there are no remaining nodes.
                                            TriggerRemoveCondition(mainTrigger, thistype.instanceIterator); // Detach the iterator.
                                    }
                                }
                                else
                                {
                                    this.onLoop(); // Call the onLoop method that the user is supposed to declare.
                                }
                                this = this.next; // Go to the next node.
                            }
                            return false;
                        });
                    }
                }
            }
        }

        method stopLooping()
        {
            if (this.alreadyAdded && integer(this) > 0) // Make sure the method was called on a valid node.
            {
                this.pendingRemoval = true; // Flag this node so that it would be removed during the next loop.
                this.alreadyAdded = false;
            }
        }

function interface LoopFunc takes nothing returns nothing

private struct events extends array
    method onLoop takes nothing returns nothing
        call LoopFunc(this).execute()
    endmethod
    implement Loop
endstruct

function OnLoop takes LoopFunc f returns nothing
    call events(f).startLooping()
endfunction
function OffLoop takes LoopFunc f returns nothing
    call events(f).stopLooping()
endfunction
endstruct

                        static method() -> boolean
                        {
                            thistype this = thistype(0).next;
                            thistype that // You could use a global to save a local declaration,
                                              // globals don't seem to be slower than locals anyway.
                            while (integer(this) != 0) // Traverse the list.
                            {
                                if (this.pendingRemoval) // See if the instance should be removed.
                                {
                                    // Remove the node from the linked list.
                                    this.previous.next = this.next;
                                    this.next.previous = this.previous;
                                
                                    this.pendingRemoval = false;
                                    if (this.alreadyAdded) // See if the instance should be readded.
                                    {
                                        // Readd it if needed.
                                        set that=this.next
                                        thistype(0).previous.next = this;
                                        this.previous = thistype(0).previous;
                                        thistype(0).previous = this;
                                        this.next = thistype(0);
                                        set this=that // Go to the next node.
                                    }
                                    else
                                    {
                                        globalCount -= 1; // Decrement the global count.

                                        if (globalCount == 0) // Check whether the timer should keep running.
                                            PauseTimer(mainTimer);

                                        if (thistype(0).next == thistype(0)) // Check if there are no remaining nodes.
                                            TriggerRemoveCondition(mainTrigger, thistype.instanceIterator); // Detach the iterator.
                                        this = this.next; // Go to the next node.
                                    }
                                }
                                else
                                {
                                    this.onLoop(); // Call the onLoop method that the user is supposed to declare.
                                    this = this.next; // Go to the next node.
                                }
                            }
                            return false;
                        });

private static boolean b=false
private method onLoop
    debug if b then
    debug     // Give an error message warning about a thread crash/op limit hit in the previous loop.
    debug endif
    debug set b=true
    // do the loop
    debug set b=false
endmethod