# README.html

# multi Version: 1.8.2 (More support for love & lanes threading!)

Note: The changes section has information on how to use the new features as they come out. Why put the infomation twice on the readme?

My multitasking library for lua
To install copy the multi folder into your enviroment and you are good to go

It is a pure lua binding if you ingore the integrations and the love2d compat

If you find any bugs or have any issues please let me know :)

- - Discord
  - Planned features/TODO
  - Known Bugs/Issues
  - Usage:
  - LOOPS
  - EVENTS
  - STEPS
  - TLOOPS
  - Connections
  - TIMERS
  - UPDATER
  - Processes
  - Queuer (WIP)
  - Threads
  - Threadable Actors
  - Functions
  - ThreadedUpdater
  - Triggers
  - Tasks
  - Jobs
  - Watchers
  - Timeout management
  - Changes

## Discord

For real-time assistance with my libraries! A place where you can ask questions and get help with any of my libraries. Also you can request features and stuff there as well.
https://discord.gg/U8UspuA

## Planned features/TODO

- Add system threads for love2d that works like the lanesManager (loveManager, slight differences).
- Improve performance of the library — It has increased a bit, but I feel I can get a little more out of it
- Improve coroutine based threading scheduling
- Add more features to support module creators
- Make a framework for eaiser thread task distributing
- Fix Error handling on threaded multi objects Non threaded multiobjs will crash your program if they error though! Use multi:newThread() of multi:newSystemThread() if your code can error! Unless you use multi:protect() this however lowers performance!
- Add multi:OnError(function(obj,err))
- sThread.wrap(obj) May or may not be completed Theory: Allows interaction in one thread to affect it in another. The addition to threaded tables may make this possible!
- SystemThreaded Actors — After some tests i figured out a way to make this work… It will work slightly different though. This is due to the actor needing to be splittable…
- LoadBalancing for system threads (Once SystemThreaded Actors are done)
- Add more integrations
- Finish the wiki stuff. (11% done)
- Test for unknown bugs

## Known Bugs/Issues

In regards to integrations, thread cancellation works slightly different for love2d and lanes. Within love2d I was unable to (To lazy to…) not use the multi library within the thread. A fix for this is to call `multi:Stop()` when you are done with your threaded code! This may change however if I find a way to work around this. In love2d in order to mimic the GLOBAL table I needed the library to constantly sync tha data… You can use the sThread.waitFor(varname), or sThread.hold(func) methods to sync the globals, to get the value instead of using GLOBAL and this could work. If you want to go this route I suggest setting multi.isRunning=true to prevent the auto runner from doing its thing! This will make the multi manager no longer function, but thats the point :P

## Usage:

    -- Basic usage Alarms: Have been moved to the core of the library require("multi") would work as well
    require("multi") -- gets the entire library
    alarm=multi:newAlarm(3) -- in seconds can go to .001 uses the built in os.clock()
    alarm:OnRing(function(a)
      print("3 Seconds have passed!")
      a:Reset(n) -- if n were nil it will reset back to 3, or it would reset to n seconds
    end)
    multi:mainloop() -- the main loop of the program, multi:umanager() exists as well to allow integration in other loops Ex: love2d love.update function. More on this binding in the wiki!

The library is modular so you only need to require what you need to. Because of this, the global enviroment is altered

There are many useful objects that you can use
Check out the wiki for detailed usage, but here are the objects:

- Process#
- Queuer#
- Alarm
- Loop
- Event
- Step
- Range
- TStep
- TLoop
- Condition
- Connection
- Timer
- Updater
- Thread*
- Trigger
- Task
- Job
- Function
- Watcher
  Note: Both a process and queue act like the multi namespace, but allows for some cool things. Because they use the other objects an example on them will be done last
  *Uses the built in coroutine features of lua, these have an interesting interaction with the other means of multi-tasking
  Triggers are kind of useless after the creation of the Connection
  Watchers have no real purpose as well I made it just because.

# Examples of each object being used

We already showed alarms in action so lets move on to a Loop object

Throughout these examples I am going to do some strange things in order to show other features of the library!

## LOOPS

    -- Loops: Have been moved to the core of the library require("multi") would work as well
    require("multi") -- gets the entire library
    count=0
    loop=multi:newLoop(function(self,dt) -- dt is delta time and self is a reference to itself
      count=count+1
      if count > 10 then
        self:Break() -- All methods on the multi objects are upper camel case, where as methods on the multi or process/queuer namespace are lower camel case
        -- self:Break() will stop the loop and trigger the OnBreak(func) method
        -- Stopping is the act of Pausing and deactivating the object! All objects can have the multiobj:Break() command on it!
      else
        print("Loop #"..count.."!")
      end
    end)
    loop:OnBreak(function(self)
      print("You broke me :(")
    end)
    multi:mainloop()

# Output

Loop #1!
Loop #2!
Loop #3!
Loop #4!
Loop #5!
Loop #6!
Loop #7!
Loop #8!
Loop #9!
Loop #10!
You broke me :(

With loops out of the way lets go down the line

This library aims to be Async like. In reality everything is still on one thread unless you are using the lanes integration module WIP (More on that later)

## EVENTS

    -- Events, these were the first objects introduced into the library. I seldomly use them in their pure form though, but later on you'll see their advance uses!
    -- Events on there own don't really do much... We are going to need 2 objects at least to get something going
    require("multi") -- gets the entire library
    count=0
    -- lets use the loop again to add to count!
    loop=multi:newLoop(function(self,dt)
      count=count+1
    end)
    event=multi:newEvent(function() return count==100 end) -- set the event
    event:OnEvent(function(self) -- connect to the event object
      loop:Pause() -- pauses the loop from running!
      print("Stopped that loop!")
    end) -- events like alarms need to be reset the Reset() command works here as well
    multi:mainloop()

# Output

Stopped that loop!

## STEPS

    require("multi")
    -- Steps, are like for loops but non blocking... You can run a loop to infintity and everything will still run I will combine Steps with Ranges in this example.
    step1=multi:newStep(1,10,1,0) -- Some explaining is due. Argument 1 is the Start # Argument 2 is the ResetAt # (inclusive) Argument 3 is the count # (in our case we are counting by +1, this can be -1 but you need to adjust your start and resetAt numbers)
    -- The 4th Argument is for skipping. This is useful for timing and for basic priority management. A priority management system is included!
    step2=multi:newStep(10,1,-1,1) -- a second step, notice the slight changes!
    step1:OnStart(function(self)
      print("Step Started!")
    end)
    step1:OnStep(function(self,pos)
      if pos<=10 then -- what what is this? the step only goes to 10!!!
        print("Stepping... "..pos)
       else
        print("How did I get here?")
       end
    end)
    step1:OnEnd(function(self)
      print("Done!")
      -- We finished here, but I feel like we could have reused this step in some way... Yeah I soule Reset() it, but what if i wanted to change it...
      if self.endAt==10 then -- lets only loop once
        self:Update(1,11,1,0) -- oh now we can reach that else condition!
      end
      -- Note Update() will restart the step!
    end)

    -- step2 is bored lets give it some love :P
    step2.range=step2:newRange() -- Set up a range object to have a nested step in a sense! Each nest requires a new range
    -- it is in your interest not to share ranges between objects! You can however do it if it suits your needs though
    step2:OnStep(function(self,pos)
      -- for 1=1,math.huge do
        --  print("Haha I am holding the code up because I can!!!")
      --end
      -- We dont want to hold things up, but we want to nest.
      -- Note a range is not nessary if the nested for loop has a small range, if however the range is rather large you may want to allow other objects to do some work
      for i in self.range(1,100) do
        print(pos,i) -- Now our nested for loop is using a range object which allows for other objects to get some cpu time while this one is running
      end
    end)
    -- TSteps are just like alarms and steps mixed together, the only difference in construction is the 4th Argument. On a TStep that argument controls time. The defualt is 1
    -- The Reset(n) works just like you would figure!
    step3=multi:newTStep(1,10,.5,2) -- lets go from 1 to 10 counting by .5 every 2 seconds
    step3:OnStep(function(self,pos)
      print("Ok "..pos.."!")
    end)
    multi:mainloop()

# Output

Note: the output on this one is huge!!! So I had to … some parts! You need to run this for your self to see what is going on!
Step Started!
Stepping… 1
10 1
Stepping… 2
10 2
Stepping… 3
10 3
…
Ok 9.5!
Ok 10!

## TLOOPS

    require("multi")
    -- TLoops are loops that run ever n second. We will also look at condition objects as well
    -- Here we are going to modify the old loop to be a little different
    count=0
    loop=multi:newTLoop(function(self) -- We are only going to coult with this loop, but doing so using a condition!
      while self:condition(self.cond) do
        count=count+1
      end
      print("Count is "..count.."!")
      self:Destroy() -- Lets destroy this object, casting it to the dark abyss MUHAHAHA!!!
      -- the reference to this object will be a phantom object that does nothing!
    end,1) -- Notice the ',1' after the function! This is where you put your time value!
    loop.cond=multi:newCondition(function() return count<=100 end) -- conditions need a bit of work before i am happy with them
    multi:mainloop()

# Output

Count is 101!

## Connections

These are my favorite objects and you’ll see why. They are very useful objects for ASync connections!

    require("multi")
    -- Lets create the events
    yawn={} -- ill just leave that there
    OnCustomSafeEvent=multi:newConnection(true) -- lets pcall the calls incase something goes wrong defualt
    OnCustomEvent=multi:newConnection(false) -- lets not pcall the calls and let errors happen... We are good at coding though so lets get a speed advantage by not pcalling. Pcalling is useful for plugins and stuff that may have been coded badly and you can ingore those connections if need be.
    OnCustomEvent:Bind(yawn) -- create the connection lookup data in yawn

    -- Lets connect to them, a recent update adds a nice syntax to connect to these
    cd1=OnCustomSafeEvent:Connect(function(arg1,arg2,...)
      print("CSE1",arg1,arg2,...)
    end,"bob") -- lets give this connection a name
    cd2=OnCustomSafeEvent:Connect(function(arg1,arg2,...)
      print("CSE2",arg1,arg2,...)
    end,"joe") -- lets give this connection a name
    cd3=OnCustomSafeEvent:Connect(function(arg1,arg2,...)
      print("CSE3",arg1,arg2,...)
    end) -- lets not give this connection a name

    -- no need for connect, but I kept that function because of backwards compatibility.
    OnCustomEvent(function(arg1,arg2,...)
      print(arg1,arg2,...)
    end)

    -- Now within some loop/other object you trigger the connection like
    OnCustomEvent:Fire(1,2,"Hello!!!") -- fire all conections

    -- You may have noticed that some events have names! See the following example!
    OnCustomSafeEvent:getConnection("bob"):Fire(1,100,"Bye!") -- fire only bob!
    OnCustomSafeEvent:getConnection("joe"):Fire(1,100,"Hello!") -- fire only joe!!
    OnCustomSafeEvent:Fire(1,100,"Hi Ya Folks!!!") -- fire them all!!!

    -- Connections have more to them than that though!
    -- As seen above cd1-cd3 these are hooks to the connection object. This allows you to remove a connection
    -- For Example:
    cd1:Remove() -- remove this connection from the master connection object
    print("------")
    OnCustomSafeEvent:Fire(1,100,"Hi Ya Folks!!!") -- fire them all again!!!
    -- To remove all connections use:
    OnCustomSafeEvent:Remove()
    print("------")
    OnCustomSafeEvent:Fire(1,100,"Hi Ya Folks!!!") -- fire them all again!!!

# Output

1 2 Hello!!!
CSE1 1 100 Bye!
CSE2 1 100 Hello!
CSE1 1 100 Hi Ya Folks!!!
CSE2 1 100 Hi Ya Folks!!!
CSE3 1 100 Hi Ya Folks!!!
CSE2 1 100 Hi Ya Folks!!!
CSE3 1 100 Hi Ya Folks!!!

You may think timers should be bundled with alarms, but they are a bit different and have cool features

## TIMERS

    -- You see the thing is that all time based objects use timers eg. Alarms, TSteps, and Loops. Timers are more low level!
    require("multi")
    local clock = os.clock
    function sleep(n)  -- seconds
      local t0 = clock()
      while clock() - t0 <= n do end
    end -- we will use this later!

    timer=multi:newTimer()
    timer:Start()
    -- lets do a mock alarm
    set=3 -- 3 seconds
    a=0
    while timer:Get()<=set do
      -- waiting...
      a=a+1
    end
    print(set.." second(s) have passed!")
    -- Timers can do one more thing that is interesting and that is pausing them!
    timer:Pause()
    print(timer:Get()) -- should be really close to 'set'
    sleep(3)
    print(timer:Get()) -- should be really close to 'set'
    timer:Resume()
    sleep(1)
    print(timer:Get()) -- should be really close to the value of set + 1
    timer:Pause()
    print(timer:Get()) -- should be really close to 'set'
    sleep(3)
    print(timer:Get()) -- should be really close to 'set'
    timer:Resume()
    sleep(1)
    print(timer:Get()) -- should be really close to the value of set + 2

# Output

Note: This will make more sense when you run it for your self
3 second(s) have passed!
3.001
3.001
4.002
4.002
4.002
5.003

## UPDATER

    -- Updaters: Have been moved to the core of the library require("multi") would work as well
    require("multi")
    updater=multi:newUpdater(5) -- really simple, think of a look with the skip feature of a step
    updater:OnUpdate(function(self)
      --print("updating...")
    end)
    -- Here every 5 steps the updater will do stuff!
    -- But I feel it is now time to touch into priority management, so lets get into basic priority stuff and get into a more advance version of it
    --[[
    multi.Priority_Core -- Highest form of priority
    multi.Priority_High
    multi.Priority_Above_Normal
    multi.Priority_Normal -- The defualt form of priority
    multi.Priority_Below_Normal
    multi.Priority_Low
    multi.Priority_Idle -- Lowest form of priority

    Note: These only take effect when you enable priority, otherwise everything is at a core like level!
    We aren't going to use regular objects to test priority, but rather benchmarks!
    to set priority on an object though you would do
    multiobj:setPriority(one of the above)
    ]]
    -- lets bench for 3 seconds using the 3 forms of priority! First no Priority
    multi:benchMark(3,nil,"Regular Bench: "):OnBench(function() -- the onbench() allows us to do each bench after each other!
      print("P1\n---------------")
      multi:enablePriority()
      multi:benchMark(3,multi.Priority_Core,"Core:")
      multi:benchMark(3,multi.Priority_High,"High:")
      multi:benchMark(3,multi.Priority_Above_Normal,"Above_Normal:")
      multi:benchMark(3,multi.Priority_Normal,"Normal:")
      multi:benchMark(3,multi.Priority_Below_Normal,"Below_Normal:")
      multi:benchMark(3,multi.Priority_Low,"Low:")
      multi:benchMark(3,multi.Priority_Idle,"Idle:"):OnBench(function()
        print("P2\n---------------")
        -- Finally the 3rd form
        multi:enablePriority2()
        multi:benchMark(3,multi.Priority_Core,"Core:")
        multi:benchMark(3,multi.Priority_High,"High:")
        multi:benchMark(3,multi.Priority_Above_Normal,"Above_Normal:")
        multi:benchMark(3,multi.Priority_Normal,"Normal:")
        multi:benchMark(3,multi.Priority_Below_Normal,"Below_Normal:")
        multi:benchMark(3,multi.Priority_Low,"Low:")
        multi:benchMark(3,multi.Priority_Idle,"Idle:")
      end)
    end)
    multi:mainloop() -- Notice how the past few examples did not need this, well only actors need to be in a loop! More on this in the wiki.

# Output

Note: These numbers will vary drastically depending on your compiler and cpu power
Regular Bench: 2094137 Steps in 3 second(s)!
P1
Below_Normal: 236022 Steps in 3 second(s)!
Normal: 314697 Steps in 3 second(s)!
Above_Normal: 393372 Steps in 3 second(s)!
High: 472047 Steps in 3 second(s)!
Core: 550722 Steps in 3 second(s)!
Low: 157348 Steps in 3 second(s)!
Idle: 78674 Steps in 3 second(s)!
P2
Core: 994664 Steps in 3 second(s)!
High: 248666 Steps in 3 second(s)!
Above_Normal: 62166 Steps in 3 second(s)!
Normal: 15541 Steps in 3 second(s)!
Below_Normal: 3885 Steps in 3 second(s)!
Idle: 242 Steps in 3 second(s)!
Low: 971 Steps in 3 second(s)!

Notice: Even though I started each bench at the same time the order that they finished differed the order is likely to vary on your machine as well!

## Processes

A process allows you to group the Actor objects within a controlable interface

    require("multi")
    proc=multi:newProcess() -- takes an optional file as an argument, but for this example we aren't going to use that
    -- a process works just like the multi object!
    b=0
    loop=proc:newTLoop(function(self)
        a=a+1
        proc:Pause() -- pauses the cpu cycler for this processor! Individual objects are not paused, however because they aren't getting cpu time they act as if they were paused
    end,.1)
    updater=proc:newUpdater(multi.Priority_Idle) -- priority can be used in skip arguments as well to manage priority without enabling it!
    updater:OnUpdate(function(self)
        b=b+1
    end)
    a=0 -- a counter
    loop2=proc:newLoop(function(self,dt)
        print("Lets Go!")
        self:hold(3) -- this will keep this object from doing anything! Note: You can only have one hold active at a time! Multiple are possible, but results may not be as they seem see * for how hold works
        -- Within a process using hold will keep it alive until the hold is satisified!
        print("Done being held for 1 second")
        self:hold(function() return a>10 end)
        print("A is now: "..a.." b is also: "..b)
        self:Destroy()
        self.Parent:Pause() -- lets say you don't have the reference to the process!
        os.exit()
    end)
    -- Notice this is now being created on the multi namespace
    event=multi:newEvent(function() return os.clock()>=1 end)
    event:OnEvent(function(self)
        proc:Resume()
        self:Destroy()
    end)
    proc:Start()
    multi:mainloop()

# Output

Lets Go!
Done being held for 1 second
A is now: 29 b is also: 479

Hold: This method works as follows

    function multi:hold(task)
        self:Pause() -- pause the current object
        self.held=true -- set held
        if type(task)=='number' then -- a sleep cmd
            local timer=multi:newTimer()
            timer:Start()
            while timer:Get()<task do -- This while loop is what makes using multiple holds tricky... If the outer while is good before the nested one then the outter one will have to wait! There is a way around this though!
                if love then
                    self.Parent:lManager()
                else
                    self.Parent:Do_Order()
                end
            end
            self:Resume()
            self.held=false
        elseif type(task)=='function' then
            local env=self.Parent:newEvent(task)
            env:OnEvent(function(envt) envt:Pause() envt.Active=false end)
            while env.Active do
                if love then
                    self.Parent:lManager()
                else
                    self.Parent:Do_Order()
                end
            end
            env:Destroy()
            self:Resume()
            self.held=false
        else
            print('Error Data Type!!!')
        end
    end

## Queuer (WIP)

A queuer works just like a process however objects are processed in order that they were created…

    require("multi")
    queue = multi:newQueuer()
    queue:newAlarm(3):OnRing(function()
        print("Ring ring!!!")
    end)
    queue:newStep(1,10):OnStep(function(self,pos)
        print(pos)
    end)
    queue:newLoop(function(self,dt)
        if dt==3 then
            self:Break()
            print("Done")
        end
    end)
    queue:Start()
    multi:mainloop()

# Expected Output

Note: the queuer still does not work as expected!
Ring ring!!!
1
2
3
4
5
6
7
8
9
10
Done

# Actual Output

Done
1
2
3
4
5
6
7
8
9
10
Ring ring!!!

## Threads

These fix the hold problem that you get with regular objects, and they work exactly the same! They even have some extra features that make them really useful.

    _require=require -- lets play with the require method a bit
    function require(path)
        path=path:gsub("%*","all")
        _require(path)
    end
    require("multi.*") -- now I can use that lovely * symbol to require everything
    -- Pointless I know I... Don't look at me like that :P
    test=multi:newThreadedProcess("main") -- you can thread processors and all Actors see note for a list of actors you can thread!
    test2=multi:newThreadedProcess("main2")
    count=0
    test:newLoop(function(self,dt)
        count=count+1
        thread.sleep(.01)
    end)
    test2:newLoop(function(self,dt)
        print("Hello!")
        thread.sleep(1) -- sleep for some time
    end)
    -- threads take a name object then the rest as normal
    step=multi:newThreadedTStep("step",1,10)
    step:OnStep(function(self,p)
        print("step",p)
        thread.skip(21) -- skip n cycles
    end)
    step:OnEnd(function()
        print("Killing thread!")
        thread.kill() -- kill the thread
    end)
    loop=multi:newThreadedLoop("loop",function(self,dt)
        print(dt)
        thread.sleep(1.1)
    end)
    loop2=multi:newThreadedLoop("loop",function(self,dt)
        print(dt)
        thread.hold(function() return count>=100 end)
        print("Count is "..count)
        os.exit()
    end)
    alarm=multi:newThreadedAlarm("alarm",1)
    alarm:OnRing(function(self)
        print("Ring")
        self:Reset()
    end)
    multi:mainloop()

# Output

Ring
0.992
0.992
Hello!
step 1
step 2
Hello!
Ring
2.092
step 3
Hello!
Ring
Count is 100

## Threadable Actors

- Alarms
- Events
- Loop/TLoop
- Process
- Step/TStep

## Functions

If you ever wanted to pause a function then great now you can
The uses of the Function object allows one to have a method that can run free in a sense

    require("multi")
    func=multi:newFunction(function(self,arg1,arg2,...)
        self:Pause()
        return arg1
    end)
    print(func("Hello"))
    print(func("Hello2")) -- returns PAUSED allows for the calling of functions that should only be called once. returns PAUSED instantly if paused
    func:Resume()
    print(func("Hello3"))

# Output

Hello
PAUSED
Hello3

## ThreadedUpdater

    -- Works the same as a regular updater!
    require("multi")
    multi:newThreadedUpdater("Test",10000):OnUpdate(function(self)
        print(self.pos)
    end)
    multi:mainloop()

# Output

1
2
…
.inf

## Triggers

Triggers were what I used before connections became a thing, also Function objects are a lot like triggers and can be paused as well, while triggers cannot…
They are simple to use, but in most cases you are better off using a connection

    require("multi")
    -- They work like connections but can only have one event binded to them
    trig=multi:newTrigger(function(self,a,b,c,...)
        print(a,b,c,...)
    end)
    trig:Fire(1,2,3)
    trig:Fire(1,2,3,"Hello",true)

# Output

1 2 3
1 2 3 Hello true

## Tasks

Tasks allow you to run a block of code before the multi mainloops does it thing. Tasks still have a use, but depending on how you program they aren’t needed.

    require("multi")
    multi:newTask(function()
        print("Hi!")
    end)
    multi:newLoop(function(self,dt)
        print("Which came first the task or the loop?")
        self:Break()
    end)
    multi:newTask(function()
        print("Hello there!")
    end)
    multi:mainloop()

# Output

Hi!
Hello there!
Which came first the task or the loop?

As seen in the example above the tasks were done before anything else in the mainloop! This is useful when making libraries around the multitasking features and you need things to happen in a certain order!

## Jobs

Jobs were a strange feature that was created for throttling connections! When I was building a irc bot around this library I couldn’t have messages posting too fast due to restrictions. Jobs allowed functions to be added to a queue that were executed after a certain amount of time has passed

    require("multi") -- jobs use alarms I am pondering if alarms should be added to the core or if jobs should use timers instead...
    -- jobs are built into the core of the library so no need to require them
    print(multi:hasJobs())
    multi:setJobSpeed(1) -- set job speed to 1 second
    multi:newJob(function()
        print("A job!")
    end,"test")

    multi:newJob(function()
        print("Another job!")
        multi:removeJob("test") -- removes all jobs with name "test"
    end,"test")

    multi:newJob(function()
        print("Almost done!")
    end,"test")

    multi:newJob(function()
        print("Final job!")
    end,"test")
    print(multi:hasJobs())
    print("There are "..multi:getJobs().." jobs in the queue!")
    multi:mainloop()

# Output

false 0
true 4
There are 4 jobs in the queue!
A job!
Another job!

## Watchers

Watchers allow you to monitor a variable and trigger an event when the variable has changed!

    require("multi")
    a=0
    watcher=multi:newWatcher(_G,"a") -- watch a in the global enviroment
    watcher:OnValueChanged(function(self,old,new)
        print(old,new)
    end)
    tloop=multi:newTLoop(function(self)
        a=a+1
    end,1)
    multi:mainloop()

# Output

0 1
1 2
2 3
…
.inf-1 inf

## Timeout management

    -- Note: I used a tloop so I could control the output of the program a bit.
    require("multi")
    a=0
    inc=1 -- change to 0 to see it not met at all, 1 if you want to see the first condition not met but the second and 2 if you want to see it meet the condition on the first go.
    loop=multi:newTLoop(function(self)
        print("Looping...")
        a=a+inc
        if a==14 then
            self:ResolveTimer("1","2","3") -- ... any number of arguments can be passed to the resolve handler
            -- this will also automatically pause the object that it is binded to
        end
    end,.1)
    loop:SetTime(1)
    loop:OnTimerResolved(function(self,a,b,c) -- the handler will return the self and the passed arguments
        print("We did it!",a,b,c)
    end)
    loop:OnTimedOut(function(self)
        if not TheSecondTry then
            print("Loop timed out!",self.Type,"Trying again...")
            self:ResetTime(2)
            self:Resume()
            TheSecondTry=true
        else
            print("We just couldn't do it!") -- print if we don't get anything working
        end
    end)
    multi:mainloop()

# Output (Change the value inc as indicated in the comment to see the outcomes!)

Looping…
Looping…
Looping…
Looping…
Looping…
Looping…
Looping…
Looping…
Looping…
Loop timed out! tloop Trying again…
Looping…
Looping…
Looping…
Looping…
Looping…
We did it! 1 2 3

## Changes

Updated from 1.8.1 to 1.8.2
Added:

- multi:newsystemThreadedTable(name) NOTE: Metatables are not supported in transfers. However there is a work around obj:init() that you see does this. Take a look in the multi/integration/shared/shared.lua files to see how I did it!
- Modified the GLOBAL metatable to sync before doing its tests
- multi._VERSION was multi.Version, felt it would be more consistant this way… I left the old way of getting the version just incase someone has used that way. It will eventually be gone. Also multi:getVersion() will do the job just as well and keep your code nice and update related bug free!
- Also everything that is included in the: multi/integration/shared/shared.lua (Which is loaded automatically) works in both lanes and love2d enviroments!

The threaded table is setup just like the threaded queue.
It provids GLOBAL like features without having to write to GLOBAL!
This is useful for module creators who want to keep their data private, but also use GLOBAL like coding.
It has a few features that makes it a bit better than plain ol GLOBAL (For now…)
(ThreadedTable - TT for short)

- TT:waitFor(name)
- TT:sync()
- TT[“var”]=value
- print(TT[“var”])

we also have the “sync” method, this one was made for love2d because we do a syncing trick to get data in a table format. The lanes side has a sync method as well so no worries. Using indexing calls sync once and may grab your variable. This allows you to have the lanes indexing ‘like’ syntax when doing regular indexing in love2d side of the module. As of right now both sides work flawlessly! And this effect is now the GLOBAL as well

On GLOBALS sync is a internal method for keeping the GLOBAL table in order. You can still use sThread.waitFor(name) to wait for variables that may of may not yet exist!

Time for some examples:

# Using multi:newSystemThreadedTable(name)

    -- lanes Desktop lua! NOTE: this is in lanesintergratetest6.lua in the examples folder
    local GLOBAL,sThread=require("multi.integration.lanesManager").init()
    test=multi:newSystemThreadedTable("YO"):init()
    test["test1"]="lol"
    multi:newSystemThread("test",function()
        tab=sThread.waitFor("YO"):init()
        print(tab:has("test1"))
        sThread.sleep(3)
        tab["test2"]="Whats so funny?"
    end)
    multi:newThread("test2",function()
        print(test:waitFor("test2"))
    end)
    multi:mainloop()

    -- love2d gaming lua! NOTE: this is in main4.lua in the love2d examples
    require("core.Library")
    GLOBAL,sThread=require("multi.integration.loveManager").init() -- load the love2d version of the lanesManager and requires the entire multi library
    require("core.GuiManager")
    gui.ff.Color=Color.Black
    test=multi:newSystemThreadedTable("YO"):init()
    test["test1"]="lol"
    multi:newSystemThread("test",function()
        tab=sThread.waitFor("YO"):init()
        print(tab["test1"])
        sThread.sleep(3)
        tab["test2"]="Whats so funny?"
    end)
    multi:newThread("test2",function()
        print(test:waitFor("test2"))
        t.text="DONE!"
    end)
    t=gui:newTextLabel("no done yet!",0,0,300,100)
    t:centerX()
    t:centerY()

Updated from 1.8.0 to 1.8.1
No real change!
Changed the structure of the library. Combined the coroutine based threads into the core!
Only compat and integrations are not part of the core and never will be by nature.
This should make the library more convient to use.
I left multi/all.lua file so if anyone had libraries/projects that used that it will still work!
Updated from 1.7.6 to 1.8.0
(How much thread could a thread thread if a thread could thread thread?)
Added:

- multi:newSystemThreadedQueue()
- multi:systemThreadedBenchmark()
- More example files
- multi:canSystemThread() — true if an integration was added false otherwise (For module creation)
- Fixed a few bugs in the loveManager

# Using multi:systemThreadedBenchmark()

    package.path="?/init.lua;"..package.path
    local GLOBAL,sThread=require("multi.integration.lanesManager").init()
    multi:systemThreadedBenchmark(3):OnBench(function(self,count)
        print("First Bench: "..count)
        multi:systemThreadedBenchmark(3,"All Threads: ")
    end)
    multi:mainloop()

# Using multi:newSystemThreadedQueue()

Quick Note: queues shared across multiple objects will be pulling from the same “queue” keep this in mind when coding! Also the queue respects direction a push on the thread side cannot be popped on the thread side… Same goes for the mainthread!

    -- in love2d, this file will be in the same example folder as before, but is named main2.lua
    require("core.Library")
    GLOBAL,sThread=require("multi.integration.loveManager").init() -- load the love2d version of the lanesManager and requires the entire multi library
    --IMPORTANT
    -- Do not make the above local, this is the one difference that the lanesManager does not have
    -- If these are local the functions will have the upvalues put into them that do not exist on the threaded side
    -- You will need to ensure that the function does not refer to any upvalues in its code. It will print an error if it does though
    -- Also each thread has a .1 second delay! This is used to generate a random values for each thread!
    require("core.GuiManager")
    gui.ff.Color=Color.Black
    function multi:newSystemThreadedQueue(name) -- in love2d this will spawn a channel on both ends
        local c={}
        c.name=name
        if love then
            if love.thread then
                function c:init()
                    self.chan=love.thread.getChannel(self.name)
                    function self:push(v)
                        self.chan:push(v)
                    end
                    function self:pop()
                        return self.chan:pop()
                    end
                    GLOBAL[self.name]=self
                    return self
                end
                return c
            else
                error("Make sure you required the love.thread module!")
            end
        else
            c.linda=lanes.linda()
            function c:push(v)
                self.linda:send("Q",v)
            end
            function c:pop()
                return ({self.linda:receive(0,"Q")})[2]
            end
            function c:init()
                return self
            end
            GLOBAL[name]=c
        end
        return c
    end
    queue=multi:newSystemThreadedQueue("QUEUE"):init()
    queue:push("This is a test")
    queue:push("This is a test2")
    queue:push("This is a test3")
    queue:push("This is a test4")
    multi:newSystemThread("test2",function()
        queue=sThread.waitFor("QUEUE"):init()
        data=queue:pop()
        while data do
            print(data)
            data=queue:pop()
        end
        queue:push("DONE!")
    end)
    multi:newThread("test!",function()
        thread.hold(function() return queue:pop() end)
        t.text="Done!"
    end)
    t=gui:newTextLabel("no done yet!",0,0,300,100)
    t:centerX()
    t:centerY()

# In Lanes

    -- The code is compatible with each other, I just wanted to show different things you can do in both examples
    -- This file can be found in the examples folder as lanesintegrationtest4.lua
    local GLOBAL,sThread=require("multi.integration.lanesManager").init()
    queue=multi:newSystemThreadedQueue("QUEUE"):init()
    queue:push("This is a test")
    queue:push("This is a test2")
    queue:push("This is a test3")
    queue:push("This is a test4")
    multi:newSystemThread("test2",function()
        queue=sThread.waitFor("QUEUE"):init()
        data=queue:pop()
        while data do
            print(data)
            data=queue:pop()
        end
        queue:push("This is a test5")
        queue:push("This is a test6")
        queue:push("This is a test7")
        queue:push("This is a test8")
    end)
    multi:newThread("test!",function() -- this is a lua thread
        thread.sleep(.1)
        data=queue:pop()
        while data do
            print(data)
            data=queue:pop()
        end
    end)
    multi:mainloop()

Updated from 1.7.5 to 1.7.6
Fixed:
Typos like always
Added:
multi:getPlatform() — returns “love2d” if using the love2d platform or returns “lanes” if using lanes for threading
examples files
In Events added method setTask(func)
The old way still works and is more convient to be honest, but I felt a method to do this was ok.

Updated:
some example files to reflect changes to the core. Changes allow for less typing
loveManager to require the compat if used so you don’t need 2 require line to retrieve the library
Updated from 1.7.4 to 1.7.5
Fixed some typos in the readme… (I am sure there are more there are always more)
Added more features for module support
TODO:
Work on performance of the library… I see 3 places where I can make this thing run quicker

I’ll show case some old versions of the multitasking library eventually so you can see its changes in days past!

Updated from 1.7.3 to 1.7.4
Added: the example folder which will be populated with more examples in the near future!
The loveManager integration that mimics the lanesManager integration almost exactly to keep coding in both enviroments as close to possible. This is done mostly for library creation support!
An example of the loveManager in action using almost the same code as the lanesintergreationtest2.lua
NOTE: This code has only been tested to work on love2d version 1.10.2 thoough it should work version 0.9.0

    require("core.Library") -- Didn't add this to a repo yet! Will do eventually... Allows for injections and other cool things
    require("multi.compat.love2d") -- allows for multitasking and binds my libraies to the love2d engine that i am using
    GLOBAL,sThread=require("multi.integration.loveManager").init() -- load the love2d version of the lanesManager
    --IMPORTANT
    -- Do not make the above local, this is the one difference that the lanesManager does not have
    -- If these are local the functions will have the upvalues put into them that do not exist on the threaded side
    -- You will need to ensure that the function does not refer to any upvalues in its code. It will print an error if it does though
    -- Also each thread has a .1 second delay! This is used to generate a random values for each thread!
    require("core.GuiManager") -- allows the use of graphics in the program.
    gui.ff.Color=Color.Black
    function comma_value(amount)
        local formatted = amount
        while true do
            formatted, k = string.gsub(formatted, "^(-?%d+)(%d%d%d)", '%1,%2')
            if (k==0) then
                break
            end
        end
        return formatted
    end
    multi:newSystemThread("test1",function() -- Another difference is that the multi library is already loaded in the threaded enviroment as well as a call to multi:mainloop()
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 1"):OnBench(function(self,c) GLOBAL["T1"]=c multi:Stop() end)
    end)
    multi:newSystemThread("test2",function() -- spawns a thread in another lua process
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 2"):OnBench(function(self,c) GLOBAL["T2"]=c multi:Stop() end)
    end)
    multi:newSystemThread("test3",function() -- spawns a thread in another lua process
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 3"):OnBench(function(self,c) GLOBAL["T3"]=c multi:Stop() end)
    end)
    multi:newSystemThread("test4",function() -- spawns a thread in another lua process
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 4"):OnBench(function(self,c) GLOBAL["T4"]=c multi:Stop() end)
    end)
    multi:newSystemThread("test5",function() -- spawns a thread in another lua process
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 5"):OnBench(function(self,c) GLOBAL["T5"]=c multi:Stop() end)
    end)
    multi:newSystemThread("test6",function() -- spawns a thread in another lua process
        multi:benchMark(sThread.waitFor("Bench"),nil,"Thread 6"):OnBench(function(self,c) GLOBAL["T6"]=c multi:Stop() end)
    end)
    multi:newSystemThread("Combiner",function() -- spawns a thread in another lua process
        function comma_value(amount)
            local formatted = amount
            while true do
                formatted, k = string.gsub(formatted, "^(-?%d+)(%d%d%d)", '%1,%2')
                if (k==0) then
                    break
                end
            end
            return formatted
        end
        local b=comma_value(tostring(sThread.waitFor("T1")+sThread.waitFor("T2")+sThread.waitFor("T3")+sThread.waitFor("T4")+sThread.waitFor("T5")+sThread.waitFor("T6")))
        GLOBAL["DONE"]=b
    end)
    multi:newThread("test0",function()
        -- sThread.waitFor("DONE") -- lets hold the main thread completely so we don't eat up cpu
        -- os.exit()
        -- when the main thread is holding there is a chance that error handling on the system threads may not work!
        -- instead we can do this
        while true do
            thread.skip(1) -- allow error handling to take place... Otherwise lets keep the main thread running on the low
            -- Before we held just because we could... But this is a game and we need to have logic continue
            --sThreadM.sleep(.001) -- Sleeping for .001 is a greeat way to keep cpu usage down. Make sure if you aren't doing work to rest. Abuse the hell out of GLOBAL if you need to :P
            if GLOBAL["DONE"] then
                t.text="Bench: "..GLOBAL["DONE"]
            end
        end
    end)
    GLOBAL["Bench"]=3
    t=gui:newTextLabel("no done yet!",0,0,300,100)
    t:centerX()
    t:centerY()

Updated from 1.7.2 to 1.7.3
Changed how requiring the library works!
`require("multi.all")` Will still work as expected; however, with the exception of threading, compat, and integrations everything else has been moved into the core of the library.

    -- This means that these are no longer required and will cause an error if done so
    require("multi.loop")
    require("multi.alarm")
    require("multi.updater")
    require("multi.tloop")
    require("multi.watcher")
    require("multi.tstep")
    require("multi.step")
    require("multi.task")
    -- ^ they are all part of the core now

Updated from 1.7.1 to 1.7.2
Moved updaters, loops, and alarms into the init.lua file. I consider them core features and they are referenced in the init.lua file so they need to exist there. Threaded versions are still separate though. Added another example file

Updated from 1.7.0 to 1.7.1 Bug fixes only

Updated from 1.6.0 to 1.7.0
Modified: multi.integration.lanesManager.lua
It is now in a stable and simple state Works with the latest lanes version! Tested with version 3.11 I cannot promise that everything will work with eariler versions. Future versions are good though.
Example Usage:
sThread is a handle to a global interface for system threads to interact with themself
thread is the interface for multithreads as seen in the threading section

GLOBAL a table that can be used throughout each and every thread

sThreads have a few methods
sThread.set(name,val) — you can use the GLOBAL table instead modifies the same table anyway
sThread.get(name) — you can use the GLOBAL table instead modifies the same table anyway
sThread.waitFor(name) — waits until a value exists, if it does it returns it
sThread.getCores() — returns the number of cores on your cpu
sThread.sleep(n) — sleeps for a bit stopping the entire thread from running
sThread.hold(n) — sleeps until a condition is met

    local GLOBAL,sThread=require("multi.integration.lanesManager").init()
    require("multi.all")
    multi:newAlarm(2):OnRing(function(self)
        GLOBAL["NumOfCores"]=sThread.getCores()
    end)
    multi:newAlarm(7):OnRing(function(self)
        GLOBAL["AnotherTest"]=true
    end)
    multi:newAlarm(13):OnRing(function(self)
        GLOBAL["FinalTest"]=true
    end)
    multi:newSystemThread("test",function() -- spawns a thread in another lua process
        require("multi.all") -- now you can do all of your coding with the multi library! You could even spawn more threads from here with the integration. You would need to require the interaction again though
        print("Waiting for variable: NumOfCores")
        print("Got it: ",sThread.waitFor("NumOfCores"))
        sThread.hold(function()
            return GLOBAL["AnotherTest"] -- note this would hold the entire systemthread. Spawn a coroutine thread using multi:newThread() or multi:newThreaded...
        end)
        print("Holding works!")
        multi:newThread("tests",function()
            thread.hold(function()
                return GLOBAL["FinalTest"] -- note this will not hold the entire systemthread. As seen with the TLoop constantly going!
            end)
            print("Final test works!")
            os.exit()
        end)
        local a=0
        multi:newTLoop(function()
            a=a+1
            print(a)
        end,.5)
        multi:mainloop()
    end)
    multi:mainloop()

Updated from 1.5.0 to 1.6.0
Changed: steps and loops

    -- Was
    step:OnStep(function(pos,self) -- same goes for tsteps as well
        print(pos)
    end)
    multi:newLoop(function(dt,self)
        print(dt)
    end)
    -- Is now
    step:OnStep(function(self,pos) -- same goes for tsteps as well
        print(pos)
    end)
    multi:newLoop(function(self,dt)
        print(dt)
    end)

Reasoning I wanted to keep objects consistant, but a lot of my older libraries use the old way of doing things. Therefore I added a backwards module

    require("multi.all")
    require("multi.compat.backwards[1,5,0]") -- allows for the use of features that were scrapped/changed in 1.6.0+

Updated from 1.4.1 to 1.5.0
Added:

- An easy way to manage timeouts
- Small bug fixes

1.4.1 - First Public release of the library

IMPORTANT:
Every update I make aims to make things simpler more efficent and just better, but a lot of old code, which can be really big, uses a lot of older features. I know the pain of having to rewrite everything. My promise to my library users is that I will always have backwards support for older features! New ways may exist that are quicker and eaiser, but the old features/methods will be supported.