Non-Actor: Timerstimer = multi:newTimer()
Creates a timer object that can keep track of time
self = timer:Start() — Starts the timer
time_elapsed = timer:Get() — Returns the time elapsed since timer:Start() was called
boolean = timer:isPaused() — Returns if the timer is paused or not
self = timer:Pause() — Pauses the timer, it skips time that would be counted during the time that it is paused
self = timer:Resume() — Resumes a paused timer. See note below
self = timer:tofile(STRING path) — Saves the object to a file at location path
Note: If a timer was paused after 1 second then resumed a second later and Get() was called a second later, timer would have 2 seconds counted though 3 really have passed.
Non-Actor: Connections
Arguable my favorite object in this library, next to threads
conn = multi:newConnection([BOOLEAN protect true])
Creates a connection object and defaults to a protective state. All calls will run within pcall()
self = conn:HoldUT([NUMBER n 0]) — Will hold futhur execution of the thread until the connection was triggered. If n is supplied the connection must be triggered n times before it will allow ececution to continue.
self = conn:FConnect(FUNCTION func) — Creates a connection that is forced to execute when Fire() is called. returns or nil = conn:Fire(…) — Triggers the connection with arguments …, “returns” if non-nil is a table containing return values from the triggered connections. [Deprecated: Planned removal in 14.x.x]
self = conn:Bind(TABLE t) — sets the table to hold the connections. Leaving it alone is best unless you know what you are doing
self = conn:Remove() — removes the bind that was put in place. This will also destroy all connections that existed before.
link = conn:connect(FUNCTION func, [STRING name nil], [NUMBER num #conns+1]) — Connects to the object using function func which will recieve the arguments passed by Fire(…). You can name a connection, which allows you to use conn:getConnection(name). Names must be unique! num is simple the position in the order in which connections are triggered. The return Link is the link to the connected event that was made. You can remove this event or even trigger it specifically if need be.
link:Fire(...) — Fires the created event
bool = link:Destroy() — returns true if success.
subConn = conn:getConnection(STRING name, BOOLEAN ingore) — returns the sub connection which matches name.
returns or nil subConn:Fire() — “returns” if non-nil is a table containing return values from the triggered connections.
self = conn:tofile(STRING path) — Saves the object to a file at location path
The connect feature has some syntax sugar to it as seen below
link = conn(FUNCTION func, [STRING name nil], [NUMBER #conns+1])
Example:
1,print("------")
OnCustomSafeEvent:Fire(1,100,"Hi Ya Folks!!!")
-
Jobs
nil = multi:newJob(FUNCTION: func, STRING: name) — Adds a job to a queue of jobs that get executed after some time. func is the job that is being ran, name is the name of the job.
nil = multi:setJobSpeed(NUMBER n) — seconds between when each job should be done.
bool, number = multi:hasJobs() — returns true if there are jobs to be processed. And the number of jobs to be processed
num = multi:getJobs() — returns the number of jobs left to be processed.
number = multi:removeJob(name) — removes all jobs of name, name. Returns the number of jobs removed
Note: Jobs may be turned into actual objects in the future.
Example:
Non-Actor: Jobsnil = multi:newJob(FUNCTION func, STRING name) — Adds a job to a queue of jobs that get executed after some time. func is the job that is being ran, name is the name of the job.
nil = multi:setJobSpeed(NUMBER n) — seconds between when each job should be done.
bool, number = multi:hasJobs() — returns true if there are jobs to be processed. And the number of jobs to be processed
num = multi:getJobs() — returns the number of jobs left to be processed.
number = multi:removeJob(STRING name) — removes all jobs of name, name. Returns the number of jobs removed
Note: Jobs may be turned into actual objects in the future.
Example:
functionprint(multi:hasJobs())
print("There are "..multi:getJobs().." jobs in the queue!")
multi:mainloop()
-
Ranges
Conditions
+
Non-Actor: Functions
func = multi:newFunction(FUNCTION func)
These objects used to have more of a function before corutine based threads came around, but the main purpose now is the ablity to have pausable function calls
... = func(...) — This is how you call your function. The first argument passed is itself when your function is triggered. See example.
self = func:Pause()
self = func:Resume()
Note: A paused function will return: nil, true
Example:
local multi = require("multi")
+printOnce = multi:newFunction(function(self,msg)
+ print(msg)
+ self:Pause()
+ return "I won't work anymore"
+end)
+a=printOnce("Hello World!")
+b,c=printOnce("Hello World!")
+print(a,b,c)
+
Non-Actor: Triggers
trigger = multi:newTrigger(FUNCTION: func(...)) — A trigger is the precursor of connection objects. The main difference is that only one function can be binded to the trigger.
self = trigger:Fire(...) — Fires the function that was connected to the trigger and passes the arguments supplied in Fire to the function given.
Universal Actor functions
All of these functions are found on actors
self = multiObj:Pause() — Pauses the actor from running
self = multiObj:Resume() — Resumes the actor that was paused
nil = multiObj:Destroy() — Removes the object from the mainloop
bool = multiObj:isPaused() — Returns true if the object is paused, false otherwise
string = multiObj:getType() — Returns the type of the object
self = multiObj:SetTime(n) — Sets a timer, and creates a special “timemaster” actor, which will timeout unless ResolveTimer is called
self = multiObj:ResolveTimer(...) — Stops the timer that was put onto the multiObj from timing out
self = multiObj:OnTimedOut(func) — If ResolveTimer was not called in time this event will be triggered. The function connected to it get a refrence of the original object that the timer was created on as the first argument.
self = multiObj:OnTimerResolved(func) — This event is triggered when the timer gets resolved. Same argument as above is passed, but the variable arguments that are accepted in resolvetimer are also passed as well.
self = multiObj:Reset(n) — In the cases where it isn’t obvious what it does, it acts as Resume()
self = multiObj:SetName(STRING name)
Actor: Events
event = multi:newEvent(FUNCTION task)
The object that started it all. These are simply actors that wait for a condition to take place, then auto triggers an event. The event when triggered once isn’t triggered again unless you Reset() it.
self = SetTask(FUNCTION func) — This function is not needed if you supplied task at construction time
self = OnEvent(FUNCTION func) — Connects to the OnEvent event passes argument self to the connectee
Example:
local multi = require("multi")
+count=0
+
+loop=multi:newLoop(function(self,dt)
+ count=count+1
+end)
+event=multi:newEvent(function() return count==100 end)
+event:OnEvent(function(self)
+ loop:Destroy()
+ print("Stopped that loop!",count)
+end)
+multi:mainloop()
+
Actor: Updates
updater = multi:newUpdater([NUMBER skip 1]) — set the amount of steps that are skipped
Updaters are a mix between both loops and steps. They were a way to add basic priority management to loops (until a better way was added). Now they aren’t as useful, but if you do not want the performance hit of turning on priority then they are useful to auro skip some loops. Note: The performance hit due to priority management is not as bas as it used to be.
self = updater:SetSkip(NUMBER n) — sets the amount of steps that are skipped
self = OnUpdate(FUNCTION func) — connects to the main trigger of the updater which is called every nth step
Example:
local multi = require("multi")
+updater=multi:newUpdater(5000)
+updater:OnUpdate(function(self)
+ print("updating...")
+end)
+multi:mainloop()
+
Actor: Alarms
alarm = multi:newAlarm([NUMBER 0]) — creates an alarm which waits n seconds
Alarms ring after a certain amount of time, but you need to reset the alarm every time it rings! Use a TLoop if you do not want to have to reset.
self = alarm:Reset([NUMBER sec current_time_set]) — Allows one to reset an alarm, optional argument to change the time until the next ring.
self = alarm:OnRing(FUNCTION func — Allows one to connect to the alarm event which is triggerd after a certain amount of time has passed.
Example:
local multi = require("multi")
+alarm=multi:newAlarm(3)
+alarm:OnRing(function(a)
+ print("3 Seconds have passed!")
+ a:Reset(n)
+end)
+multi:mainloop()
+
Actor: Loops
loop = multi:newLoop(FUNCTION func) — func the main connection that you can connect to. Is optional, but you can also use OnLoop(func) to connect as well.
Loops are events that happen over and over until paused. They act like a while loop.
self = OnLoop(FUNCTION func) — func the main connection that you can connect to. Alllows multiple connections to one loop if need be.
Example:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+local a = 0
+loop = multi:newLoop(function()
+ a = a + 1
+ if a == 1000 then
+ print("a = 1000")
+ loop:Pause()
+ end
+end)
+multi:mainloop()
+
Actor: TLoops
tloop = multi:newTLoop(FUNCTION func ,NUMBER: [set 1]) — TLoops are pretty much the same as loops. The only difference is that they take set which is how long it waits, in seconds, before triggering function func.
self = OnLoop(FUNCTION func) — func the main connection that you can connect to. Alllows multiple connections to one TLoop if need be.
Example:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+local a = 0
+loop = multi:newTLoop(function()
+ a = a + 1
+ if a == 10 then
+ print("a = 10")
+ loop:Pause()
+ end
+end,1)
+multi:mainloop()
+
Actor: Steps
step = multi:newStep(NUMBER start,*NUMBER reset, [NUMBER count 1], [NUMBER skip 0]) — Steps were originally introduced to bs used as for loops that can run parallel with other code. When using steps think of it like this: for i=start,reset,count do When the skip argument is given, each time the step object is given cpu cycles it will be skipped by n cycles. So if skip is 1 every other cpu cycle will be alloted to the step object.
self = step:OnStart(FUNCTION func(self)) — This connects a function to an event that is triggered everytime a step starts.
self = step:OnStep(FUNCTION func(self,i)) — This connects a function to an event that is triggered every step or cycle that is alloted to the step object
self = step:OnEnd(FUNCTION func(self)) — This connects a function to an event that is triggered when a step reaches its goal
self = step:Update(NUMBER start,*NUMBER reset, [NUMBER count 1], [NUMBER skip 0]) — Update can be used to change the goals of the step. You should call step:Reset() after using Update to restart the step.
Example:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+multi:newStep(1,10,1,0):OnStep(function(step,pos)
+ print(step,pos)
+end):OnEnd(fucntion(step)
+ step:Destroy()
+end)
+multi:mainloop()
+
Actor: TSteps
tstep = multi:newStep(NUMBER start, NUMBER reset, [NUMBER count 1], [NUMBER set 1]) — TSteps work just like steps, the only difference is that instead of skip, we have set which is how long in seconds it should wait before triggering the OnStep() event.
self = tstep:OnStart(FUNCTION func(self)) — This connects a function to an event that is triggered everytime a step starts.
self = tstep:OnStep(FUNCTION func(self,i)) — This connects a function to an event that is triggered every step or cycle that is alloted to the step object
self = tstep:OnEnd(FUNCTION func(self)) — This connects a function to an event that is triggered when a step reaches its goal
self = tstep:Update(NUMBER start,*NUMBER reset, [NUMBER count 1], [NUMBER set 1]) — Update can be used to change the goals of the step. You should call step:Reset() after using Update to restart the step.
self = tstep:Reset([NUMBER n set]) — Allows you to reset a tstep that has ended, but also can change the time between each trigger.
Example:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+multi:newTStep(1,10,1,1):OnStep(function(step,pos)
+ print(step,pos)
+end):OnEnd(fucntion(step)
+ step:Destroy()
+end)
+multi:mainloop()
+
Actor: Time Stampers
stamper = multi:newTimeStamper() — This allows for long time spans as well as short time spans.
stamper = stamper:OhSecond(NUMBER second, FUNCTION func) — This takes a value between 0 and 59. This event is called once every second! Not once every second! If you want seconds then use alarms*! 0 is the start of every minute and 59 is the end of every minute.
stamper = stamper:OhMinute(NUMBER minute, FUNCTION func) — This takes a value between 0 and 59. This event is called once every hour*! Same concept as OnSecond()
stamper = stamper:OhHour(NUMBER hour, FUNCTION func) — This takes a value between 0 and 23. This event is called once every day*! 0 is midnight and 23 is 11pm if you use 12 hour based time.
stamper = stamper:OnDay(STRING/NUMBER day, FUNCTION func) — So the days work like this ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, ‘Sat’. When in string form this is called every week. When in number form this is called every month*!
There is a gotcha though with this. Months can have 28,29,30, and 31 days to it, which means that something needs to be done when dealing with the last few days of a month. I am aware of this issue and am looking into a solution that is simple and readable. I thought about allowing negitive numbers to allow one to eaisly use the last day of a month. -1 is the last day of the month where -2 is the second to last day of the month. You can go as low as -28 if you want, but this provides a nice way to do something near the end of the month that is lua like.
stamper = stamper:OnMonth(NUMBER month,FUNCTION func) — This takes a value between 1 and 12. 1 being January and 12 being December. Called once per year*.
stamper = stamper:OnYear(NUMBER year,FUNCTION func) — This takes a number yy. for example 18 do not use yyyy format! Odds are you will not see this method triggered more than once, unless science figures out the whole life extension thing. But every century this event is triggered*! I am going to be honest though, the odds of a system never reseting for 100 years is very unlikely, so if I used 18 (every 18th year in each century every time i load my program this event will be triggered). Does it actually work? I have no idea tbh it should, but can i prove that without actually testing it? Yes by using fake data thats how.
stamper = stamper:OnTime(NUMBER hour,NUMBER minute,NUMBER second,FUNCTION func) — This takes in a time to trigger, hour, minute, second. This triggeres once a day at a certain time! Sort of like setting an alarm! You can combine events to get other effects like this!
stamper = stamper:OnTime(STRING time,FUNCTION func) — This takes a string time that should be formatted like this: “hh:mm:ss” hours minutes and seconds must be given as parameters! Otherwise functions as above!
*If your program crashes or is rebooted than the data in RAM letting the code know that the function was already called will be reset! This means that if an event set to be triggered on Monday then you reboot the code it will retrigger that event on the same day if the code restarts. In a future update I am planning of writing to the disk for OnHour/Day/Week/Year events. This will be an option that can be set on the object.
Examples:
OnSecond
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+local a = 0
+ts:OnSecond(0,function()
+ a=a+1
+ print("New Minute: "..a.." <"..os.date("%M")..">")
+end)
+multi:mainloop()
+
OnMinute
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+local a = 0
+ts:OnSecond(0,function()
+ a=a+1
+ print("New Hour: "..a.." <"..os.date("%I")..">")
+end)
+multi:mainloop()
+
OnHour
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnHour(0,function()
+ print("New Day")
+end)
+multi:mainloop()
+
OnDay
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnDay("Thu",function()
+ print("It's thursday!")
+end)
+multi:mainloop()
+
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnDay(2,function()
+ print("Second day of the month!")
+end)
+multi:mainloop()
+
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnDay(-1,function()
+ print("Last day of the month!")
+end)
+multi:mainloop()
+
OnYear
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnYear(19,function()
+ print("We did it!")
+end)
+multi:mainloop()
+
OnTime
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnTime(12,1,0,function()
+ print("Whooooo")
+end)
+multi:mainloop()
+
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+ts = multi:newTimeStamper()
+ts:OnTime("12:04:00",function()
+ print("Whooooo")
+end)
+multi:mainloop()
+
Actor: Watchers
Deprecated: This object was removed due to its uselessness. Metatables will work much better for what is being done. Perhaps in the future i will remake this method to use metamethods instead of basic watching every step. This will most likely be removed in the next version of the library or changed to use metatables and metamethods.
watcher = multi:newWatcher(STRING name) — Watches a variable on the global namespace
watcher = multi:newWatcher(TABLE namespace, STRING name) — Watches a variable inside of a table
watcher = watcher::OnValueChanged(Function func(self, old_value, current_value))
Example
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+test = {a=0}
+watcher = multi:newWatcher(test,"a")
+watcher:OnValueChanged(function(self, old_value, current_value)
+ print(old_value,current_value)
+end)
+multi:newTLoop(function()
+ test.a=test.a + 1
+end,.5)
+multi:mainloop()
+
Actor: Custom Object
cobj = multi:newCustomObject(TABLE objRef, BOOLEAN isActor [false]) — Allows you to create your own multiobject that runs each allotted step. This allows you to create your own object that works with all the features that each built in multi object does. If isActor is set to true you must have an Act method in your table. See example below. If an object is not an actor than the Act method will not be automatically called for you.
Example:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+local work = false
+ticktock = multi:newCustomObject({
+ timer = multi:newTimer(),
+ Act = function(self)
+ if self.timer:Get()>=1 then
+ work = not work
+ if work then
+ self.OnTick:Fire()
+ else
+ self.OnTock:Fire()
+ end
+ self.timer:Reset()
+ end
+ end,
+ OnTick = multi:newConnection(),
+ OnTock = multi:newConnection(),
+},true)
+ticktock.OnTick(function()
+ print("Tick")
+end)
+ticktock.OnTock(function()
+ print("Tock")
+end)
+multi:mainloop()
+
Coroutine based Threading (CBT)
This was made due to the limitations of multiObj:hold(), which no longer exists. When this library was in its infancy and before I knew about coroutines, I actually tried to emulate what coroutines did in pure lua.
The threaded bariants of the non threaded objects do exist, but there isn’t too much of a need to use them.
The main benefits of using the coroutine based threads is the thread.* namespace which gives you the ability to easily run code side by side.
A quick note on how threads are managed in the library. The library contains a scheduler which keeps track of coroutines and manages them. Coroutines take some time then give off processing to another coroutine. Which means there are some methods that you need to use in order to hand off cpu time to other coroutines or the main thread. You must hand off cpu time when inside of a non ending loop or your code will hang. Threads also have a slight delay before starting, about 3 seconds.
threads.*
thread.sleep(NUMBER n) — Holds execution of the thread until a certain amount of time has passed
thread.hold(FUNCTION func) — Hold execttion until the function returns true
thread.skip(NUMBER n) — How many cycles should be skipped until I execute again
thread.kill() — Kills the thread
thread.yeild() — Is the same as using thread.skip(0) or thread.sleep(0), hands off control until the next cycle
thread.isThread() — Returns true if the current running code is inside of a coroutine based thread
thread.getCores() — Returns the number of cores that the current system has. (used for system threads)
thread.set(STRING name, VARIABLE val) — A global interface where threads can talk with eachother. sets a variable with name and its value
thread.get(STRING name) — Gets the data stored in name
thread.waitFor(STRING name) — Holds executon of a thread until variable name exists
thread.testFor(STRING name,VARIABLE val,STRING sym) — holds execution untile variable name exists and is compared to val
sym can be equal to: “=”, “==”, “<”, “>”, “<=”, or “>=” the way comparisan works is: “return val sym valTested“
CBT: Thread
multi:newThread(STRING name,FUNCTION func) — Creates a new thread with name and function.
Note: newThread() returns nothing. Threads are opperated hands off everything that happens, does so inside of its functions.
Threads simplify many things that you would use non CBT objects for. I almost solely use CBT for my current programming. I will slso show the above custom object using threads instead. Yes its cool and can be done.
Examples:
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+multi:newThread("Example of basic usage",function()
+ while true do
+ thread.sleep(1)
+ print("We just made an alarm!")
+ end
+end)
+multi:mainloop()
+
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+
+function multi:newTickTock()
+ local work = false
+ local _alive = true
+ local OnTick = multi:newConnection()
+ local OnTock = multi:newConnection()
+ local c =multi:newCustomObject{
+ OnTick = OnTick,
+ OnTock = OnTock,
+ Destroy = function()
+ _alive = false
+ end
+ }
+ multi:newThread("TickTocker",function()
+ while _alive do
+ thread.sleep(1)
+ work = not work
+ if work then
+ OnTick:Fire()
+ else
+ OnTock:Fire()
+ end
+ end
+ thread.kill()
+ end)
+ return c
+end
+ticktock = multi:newTickTock()
+ticktock.OnTick(function()
+ print("Tick")
+
+end)
+ticktock.OnTock(function()
+ print("Tock")
+end)
+multi:mainloop()
+
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+
+multi:newThread("TickTocker",function()
+ print("Waiting for variable a to exist...")
+ ret,ret2 = thread.hold(function()
+ return a~=nil, "test!"
+ end)
+ print(ret,ret2)
+end)
+multi:newAlarm(3):OnRing(function() a = true end)
+
+multi:mainloop()
+
CBT: Threaded Process
process = multi:newThreadedProcess(STRING name) — Creates a process object that is able allows all processes created on it to use the thread.* namespace
nil = process:getController() — Returns nothing there is no “controller” when using threaded processes
self = process:Start() — Starts the processor
self = process:Pause() — Pauses the processor
self = process:Resume() — Resumes a paused processor
self = process:Kill() — Kills/Destroys the process thread
self = process:Remove() — Destroys/Kills the processor and all of the Actors running on it
self = process:Sleep(NUMBER n) — Forces a process to sleep for n amount of time
self = process:Hold(FUNCTION/NUMBER n) — Forces a process to either test a condition or sleep.
Everything eles works as if you were using the multi. interface. You can create multi objects on the process and the objects are able to use the thread. interface.
Note: When using Hold/Sleep/Skip on an object created inside of a threaded process, you actually hold the entire process! Which means all objects on that process will be stopping until the conditions are met!
Example:
test = multi:newThreadedProcess("test")
+test:newLoop(function()
+ print("HI!")
+end)
+test:newLoop(function()
+ print("HI2!")
+ thread.sleep(.5)
+end)
+multi:newAlarm(3):OnRing(function()
+ test:Sleep(10)
+end)
+test:Start()
+multi:mainloop()
+
CBT: Hyper Threaded Process
process = multi:newHyperThreadedProcess(STRING name) — Creates a process object that is able allows all processes created on it to use the thread.* namespace. Hold/Sleep/Skip can be used in each multi obj created without stopping each other object that is running, but allows for one to pause/halt a process and stop all objects running in that process.
nil = process:getController() — Returns nothing there is no “controller” when using threaded processes
self = process:Start() — Starts the processor
self = process:Pause() — Pauses the processor
self = process:Resume() — Resumes a paused processor
self = process:Kill() — Kills/Destroys the process thread
self = process:Remove() — Destroys/Kills the processor and all of the Actors running on it
self = process:Sleep(NUMBER n) — Forces a process to sleep for n amount of time
self = process:Hold(FUNCTION/NUMBER n) — Forces a process to either test a condition or sleep.
Example:
test = multi:newHyperThreadedProcess("test")
+test:newLoop(function()
+ print("HI!")
+end)
+test:newLoop(function()
+ print("HI2!")
+ thread.sleep(.5)
+end)
+multi:newAlarm(3):OnRing(function()
+ test:Sleep(10)
+end)
+test:Start()
+multi:mainloop()
+
Same example as above, but notice how this works opposed to the non hyper version
System Threads (ST) - Multi-Integration Getting Started
The system threads need to be required seperatly.
local GLOBAL, THREAD = require("multi.integration.lanesManager").init()#
+GLOBAL, THREAD = require("multi.integration.loveManager").init()
+GLOBAL, THREAD = require("luvitManager")
+
Using this integration modifies some methods that the multi library has.
multi:canSystemThread() — Returns true is system threading is possible
multi:getPlatform() — Returns (for now) either “lanes”, “love2d” and “luvit”
This variable is created on the main thread only inside of the multi namespace: multi.isMainThread = true
This is used to know which thread is the main thread. When network threads are being discussed there is a gotcha that needs to be addressed.
* GLOBAL and THREAD do not work currently when using the luvit integration
#So you may have noticed that when using the lanes manager you need to make the global and thread local, this is due to how lanes copies local variables between states. Also love2d does not require this, actually things will break if this is done! Keep these non local since the way threading is handled at the lower level is much different anyway so GLOBAL and THREAD is automatically set up for use within a spawned thread!
ST - THREAD namespace
THREAD.set(STRING name, VALUE val) — Sets a value in GLOBAL
THREAD.get(STRING name) — Gets a value in GLOBAL
THREAD.waitFor(STRING name) — Waits for a value in GLOBAL to exist
THREAD.testFor(STRING name, VALUE val, STRING sym) — NOT YET IMPLEMENTED but planned
THREAD.getCores() — Returns the number of actual system threads/cores
THREAD.kill() — Kills the thread
THREAD.getName() — Returns the name of the working thread
THREAD.sleep(NUMBER n) — Sleeps for an amount of time stopping the current thread
THREAD.hold(FUNCTION func) — Holds the current thread until a condition is met
THREAD.getID() — returns a unique ID for the current thread. This varaiable is visible to the main thread as well by accessing it through the returned thread object. OBJ.Id
ST - GLOBAL namespace
Treat global like a table.
GLOBAL["name"] = "Ryan"
+print(GLOBAL["name"])
+
Removes the need to use THREAD.set() and THREAD.get()
ST - System Threads
systemThread = multi:newSystemThread(STRING thread_name,FUNCTION spawned_function,ARGUMENTS ...) — Spawns a thread with a certain name.
systemThread:kill() — kills a thread; can only be called in the main thread!
systemThread.OnError(FUNCTION(systemthread,errMsg,errorMsgWithThreadName))
System Threads are the feature that allows a user to interact with systen threads. It differs from regular coroutine based thread in how it can interact with variables. When using system threads the GLOBAL table is the “only way”* to send data. Spawning a System thread is really simple once all the required libraries are in place. See example below:
local multi = require("multi")
+local GLOBAL, THREAD = require("multi.integration.lanesManager").init()
+multi:newSystemThread("Example thread",function()
+ local multi = require("multi")
+ print("We have spawned a thread!")
+
+ print("Lets have a non ending loop!")
+ while true do
+
+ end
+end,"A message that we are passing")
+
+tloop = multi:newTLoop(function()
+ print("I'm still kicking!")
+end,1)
+multi:mainloop()
+
*This isn’t entirely true, as of right now the compatiablity with the lanes library and love2d engine have their own methods to share data, but if you would like to have your code work in both enviroments then using the GLOBAL table and the data structures provided by the multi library will ensure this happens. If you do not plan on having support for both platforms then feel free to use linda’s in lanes and channels in love2d.
Note: luvit currently has very basic support, it only allows the spawning of system threads, but no way to send data back and forth as of yet. I do not know if this is doable or not, but I will keep looking into it. If I can somehow emulate System Threaded Queues and the GLOBAL tabke then all other datastructures will work!
ST - System Threaded Objects
Great we are able to spawn threads, but unless your working with a process that works on passed data and then uses a socket or writes to the disk I can’t do to much with out being able to pass data between threads. This section we will look at how we can share objects between threads. In order to keep the compatibility between both love2d and lanes I had to format the system threaded objects in a strange way, but they are consistant and should work on both enviroments.
When creating objects with a name they are automatically exposed to the GLOBAL table. Which means you can retrieve them from a spawned thread. For example we have a queue object, which will be discussed in more detail next.
+multi = require("multi")
+local GLOBAL, THREAD = require("multi.integration.lanesManager").init()
+queue = multi:newSystemThreadedQueue("myQueue"):init()
+queue:push("This is a test!")
+multi:newSystemThread("Example thread",function()
+ queue = THREAD.waitFor("myQueue"):init()
+ local data = queue:pop()
+ print(data)
+end)
+multi:mainloop()
+
ST - SystemThreadedQueue
queue(nonInit) = multi:newSystemThreadedQueue(STRING name) — You must enter a name!
queue = queue:init() — initiates the queue, without doing this it will not work
void = queue:push(DATA data) — Pushes data into a queue that all threads that have been shared have access to
data = queue:pop() — pops data from the queue removing it from all threads
data = queue:peek() — looks at data that is on the queue, but dont remove it from the queue
This object the System Threaded Queue is the basis for all other data structures that a user has access to within the “shared” objects.
General tips when using a queue. You can always pop from a queue without worrying if another thread poped that same data, BUT if you are peeking at a queue there is the possibility that another thread popped the data while you are peeking and this could cause an issue, depends on what you are doing though. It’s important to keep this in mind when using queues.
Let’s get into some examples:
multi = require("multi")
+thread_names = {"Thread_A","Thread_B","Thread_C","Thread_D"}
+local GLOBAL, THREAD = require("multi.integration.lanesManager").init()
+queue = multi:newSystemThreadedQueue("myQueue"):init()
+for _,n in pairs(thread_names) do
+ multi:newSystemThread(n,function()
+ queue = THREAD.waitFor("myQueue"):init()
+ local name = THREAD.getName()
+ local data = queue:pop()
+ while data do
+ print(name.." "..data)
+ data = queue:pop()
+ end
+ end)
+end
+for i=1,100 do
+ queue:push(math.random(1,1000))
+end
+multi:newEvent(function()
+ return not queue:peek()
+end):OnEvent(function()
+ print("No more data within the queue!")
+ os.exit()
+end)
+multi:mainloop()
+
You have probable noticed that the output from this is a total mess! Well I though so too, and created the system threaded console!
ST - SystemThreadedConsole
console(nonInit) = multi:newSystemThreadedConsole(STRING name) — Creates a console object called name. The name is mandatory!
concole = console:inti() — initiates the console object
console:print(...) — prints to the console
console:write(msg) — writes to the console, to be fair you wouldn’t want to use this one.
The console makes printing from threads much cleaner. We will use the same example from above with the console implemented and compare the outputs and how readable they now are!
multi = require("multi")
+thread_names = {"Thread_A","Thread_B","Thread_C","Thread_D"}
+local GLOBAL, THREAD = require("multi.integration.lanesManager").init()
+multi:newSystemThreadedConsole("console"):init()
+queue = multi:newSystemThreadedQueue("myQueue"):init()
+for _,n in pairs(thread_names) do
+ multi:newSystemThread(n,function()
+ local queue = THREAD.waitFor("myQueue"):init()
+ local console = THREAD.waitFor("console"):init()
+ local name = THREAD.getName()
+ local data = queue:pop()
+ while data do
+
+ console:print(name.." "..data)
+ data = queue:pop()
+ end
+ end)
+end
+for i=1,100 do
+ queue:push(math.random(1,1000))
+end
+multi:newEvent(function()
+ return not queue:peek()
+end):OnEvent(function()
+ multi:newAlarm(.1):OnRing(function()
+ print("No more data within the queue!")
+ os.exit()
+ end)
+end)
+multi:mainloop()
+
As you see the output here is so much cleaner, but we have a small gotcha, you probably noticed that I used an alarm to delay the exiting of the program for a bit. This is due to how the console object works, I send all the print data into a queue that the main thread then reads and prints out when it looks at the queue. This should not be an issue since you gain so much by having clean outputs!
Another thing to note, because system threads are put to work one thread at a time, really quick though, the first thread that is loaded is able to complete the tasks really fast, its just printing after all. If you want to see all the threads working uncomment the code with THREAD.sleep(.1)
ST - SystemThreadedJobQueue
ST - SystemThreadedConnection - WIP*
connection(nonInit) = multi:newSystemThreadedConnection(name,protect) — creates a connecion object
connection = connection:init() — initaties the connection object
connectionID = connection:connect(FUNCTION func) — works like the regular connect function
void = connection:holdUT(NUMBER/FUNCTION n) — works just like the regular holdut function
void = connection:Remove() — works the same as the default
voic = connection:Fire(ARGS ...) — works the same as the default
In the current form a connection object requires that the multi:mainloop() is running on the threads that are sharing this object! By extention since SystemThreadedTables rely on SystemThreadedConnections they have the same requirements. Both objects should not be used for now.
Since the current object is not in a stable condition, I will not be providing examples of how to use it just yet!
*The main issue we have with the connection objects in this form is proper comunication and memory managament between threads. For example if a thread crashes or no longer exists the current apporach to how I manage the connection objects will cause all connections to halt. This feature is still being worked on and has many bugs to be patched out. for now only use for testing purposes.
ST - SystemThreadedTable - WIP*
ST - SystemThreadedBenchmark
bench = multi:SystemThreadedBenchmark(NUMBER seconds) — runs a benchmark for a certain amount of time
bench:OnBench(FUNCTION callback(NUMBER steps/second))
multi = require("multi")
+local GLOBAL, THREAD = require("multi.integration.lanesManager").init()
+multi:SystemThreadedBenchmark(1).OnBench(function(...)
+ print(...)
+end)
+multi:mainloop()
+
ST - SystemThreadedExecute WIP* Might remove
Network Threads - Multi-Integration
diff --git a/changes.html b/changes.html
index f1ea71b..4c957a4 100644
--- a/changes.html
+++ b/changes.html
@@ -12,209 +12,315 @@
Changes
-Update 12.2.2 Time for some more bug fixes!
Fixed: multi.Stop() not actually stopping due to the new pirority management scheme and preformance boost changes.
Thats all for this update
Update 12.2.1 Time for some bug fixes!
Fixed: SystemThreadedJobQueues
+Update 13.0.0 Added some documentation, and some new features too check it out!
Quick note on the 13.0.0 update:
This update I went all in finding bugs and improving proformance within the library. I added some new features and the new task manager, which I used as a way to debug the library was a great help, so much so thats it is now a permanent feature. It’s been about half a year since my last update, but so much work needed to be done. I hope you can find a use in your code to use my library. I am extremely proud of my work; 7 years of development, I learned so much about lua and programming through the creation of this library. It was fun, but there will always be more to add and bugs crawling there way in. I can’t wait to see where this library goes in the future!
Fixed: Tons of bugs, I actually went through the entire library and did a full test of everything, I mean everything, while writing the documentation.
Changed:
+- A few things, to make concepts in the library more clear.
- The way functions returned paused status. Before it would return “PAUSED” now it returns nil, true if paused
- Modified the connection object to allow for some more syntaxial suger!
- System threads now trigger an OnError connection that is a member of the object itself. multi.OnError() is no longer triggered for a system thread that crashes!
Connection Example:
loop = multi:newTLoop(function(self)
+ self:OnLoops()
+end,1)
+loop.OnLoops = multi:newConnection()
+loop.OnLoops(function()
+ print("Looping")
+end)
+multi:mainloop()
+
Function Example:
func = multi:newFunction(function(self,a,b)
+ self:Pause()
+ return 1,2,3
+end)
+print(func())
+print(func())
+
Removed:
+- Ranges and conditions — corutine based threads can emulate what these objects did and much better!
- Due to the creation of hyper threaded processes the following objects are no more!
— multi:newThreadedEvent()
— multi:newThreadedLoop()
— multi:newThreadedTLoop()
— multi:newThreadedStep()
— multi:newThreadedTStep()
— multi:newThreadedAlarm()
— multi:newThreadedUpdater()
— multi:newTBase() — Acted as the base for creating the other objects
These didn’t have much use in their previous form, but with the addition of hyper threaded processes the goals that these objects aimed to solve are now possible using a process
Fixed:
+- There were some bugs in the networkmanager.lua file. Desrtoy -> Destroy some misspellings.
- Massive object management bugs which caused performance to drop like a rock.
- Found a bug with processors not having the Destroy() function implemented properly.
- Found an issue with the rockspec which is due to the networkManager additon. The net Library and the multi Library are now codependent if using that feature. Going forward you will have to now install the network library separately
- Insane proformance bug found in the networkManager file, where each connection to a node created a new thread (VERY BAD) If say you connected to 100s of threads, you would lose a lot of processing power due to a bad implementation of this feature. But it goes futhur than this, the net library also creates a new thread for each connection made, so times that initial 100 by about 3, you end up with a system that quickly eats itself. I have to do tons of rewriting of everything. Yet another setback for the 13.0.0 release (Im releasing 13.0.0 though this hasn’t been ironed out just yet)
- Fixed an issue where any argument greater than 256^2 or 65536 bytes is sent the networkmanager would soft crash. This was fixed by increading the limit to 256^4 or 4294967296. The fix was changing a 2 to a 4. Arguments greater than 256^4 would be impossible in 32 bit lua, and highly unlikely even in lua 64 bit. Perhaps someone is reading an entire file into ram and then sending the entire file that they read over a socket for some reason all at once!?
- Fixed an issue with processors not properly destroying objects within them and not being destroyable themselves
- Fixed a bug where pause and resume would duplicate objects! Not good
- Noticed that the switching of lua states, corutine based threading, is slower than multi-objs (Not by much though).
- multi:newSystemThreadedConnection(name,protect) — I did it! It works and I believe all the gotchas are fixed as well.
— Issue one, if a thread died that was connected to that connection all connections would stop since the queue would get clogged! FIXED
— There is one thing, the connection does have some handshakes that need to be done before it functions as normal!
Added:
+- Documentation, the purpose of 13.0.0, orginally going to be 12.2.3, but due to the amount of bugs and features added it couldn’t be a simple bug fix update.
- multi:newHyperThreadedProcess(STRING name) — This is a version of the threaded process that gives each object created its own coroutine based thread which means you can use thread.* without affecting other objects created within the hyper threaded processes. Though, creating a self contained single thread is a better idea which when I eventually create the wiki page I’ll discuss
- multi:newConnector() — A simple object that allows you to use the new connection Fire syntax without using a multi obj or the standard object format that I follow.
- multi:purge() — Removes all references to objects that are contained withing the processes list of tasks to do. Doing this will stop all objects from functioning. Calling Resume on an object should make it work again.
- multi:getTasksDetails(STRING format) — Simple function, will get massive updates in the future, as of right now It will print out the current processes that are running; listing their type, uptime, and priority. More useful additions will be added in due time. Format can be either a string “s” or “t” see below for the table format
- multi:endTask(TID) — Use multi:getTasksDetails(“t”) to get the tid of a task
- multi:enableLoadDetection() — Reworked how load detection works. It gives better values now, but it still needs some work before I am happy with it
- THREAD.getID() — returns a unique ID for the current thread. This varaiable is visible to the main thread as well by accessing it through the returned thread object. OBJ.Id Do not confuse this with thread.* this refers to the system threading interface. Each thread, including the main thread has a threadID the main thread has an ID of 0!
- multi.print(…) works like normal print, but only prints if the setting print is set to true
- setting:
print enables multi.print() to work - STC: IgnoreSelf defaults to false, if true a Fire command will not be sent to the self
- STC: OnConnectionAdded(function(connID)) — Is fired when a connection is added you can use STC:FireTo(id,…) to trigger a specific connection. Works like the named non threaded connections, only the id’s are genereated for you.
- STC: FireTo(id,…) — Described above.
package.path="?/init.lua;?.lua;"..package.path
+local multi = require("multi")
+conn = multi:newConnector()
+conn.OnTest = multi:newConnection()
+conn.OnTest(function()
+ print("Yes!")
+end)
+test = multi:newHyperThreadedProcess("test")
+test:newTLoop(function()
+ print("HI!")
+ conn:OnTest()
+end,1)
+test:newLoop(function()
+ print("HEY!")
+ thread.sleep(.5)
+end)
+multi:newAlarm(3):OnRing(function()
+ test:Sleep(10)
+end)
+test:Start()
+multi:mainloop()
+
Table format for getTasksDetails(STRING format)
{
+ {TID = 1,Type="",Priority="",Uptime=0}
+ {TID = 2,Type="",Priority="",Uptime=0}
+ ...
+ {TID = n,Type="",Priority="",Uptime=0}
+ ThreadCount = 0
+ threads={
+ [Thread_Name]={
+ Uptime = 0
+ }
+ }
+}
+
Note: After adding the getTasksDetails() function I noticed many areas where threads, and tasks were not being cleaned up and fixed the leaks. I also found out that a lot of tasks were starting by default and made them enable only. If you compare the benchmark from this version to last version you;ll notice a signifacant increase in performance.
Going forward:
+- Work on system threaded functions
- work on the node manager
- patch up bugs
- finish documentstion
Update 12.2.2 Time for some more bug fixes!
Fixed: multi.Stop() not actually stopping due to the new pirority management scheme and preformance boost changes.
Thats all for this update
Update 12.2.1 Time for some bug fixes!
Fixed: SystemThreadedJobQueues
- You can now make as many job queues as you want! Just a warning when using a large amount of cores for the queue it takes a second or 2 to set up the jobqueues for data transfer. I am unsure if this is a lanes thing or not, but love2d has no such delay when setting up the jobqueue!
- You now connect to the OnReady in the jobqueue object. No more holding everything else as you wait for a job queue to be ready
- Jobqueues:doToAll now passes the queues multi interface as the first and currently only argument
- No longer need to use jobqueue.OnReady() The code is smarter and will send the pushed jobs automatically when the threads are ready
Fixed: SystemThreadedConnection
- They work the exact same way as before, but actually work as expected now. The issue before was how i implemented it. Now each connection knows the number of instances of that object that ecist. This way I no longer have to do fancy timings that may or may not work. I can send exactly enough info for each connection to consume from the queue.
Removed: multi:newQueuer
-- This feature has no real use after corutine based threads were introduced. You can use those to get the same effect as the queuer and do it better too.
Going forward:
+- This feature has no real use after corutine based threads were introduced. You can use those to get the same effect as the queuer and do it better too.
Going forwardGoing forward:
- Will I ever finish steralization? Who knows, but being able to save state would be nice. The main issue is there is no simple way to save state. While I can provide methods to allow one to turn the objects into strings and back, there is no way for me to make your code work with it in a simple way. For now only the basic functions will be here.
- I need to make better documentation for this library as well. In its current state, all I have are examples and not a list of what is what.
Example