well version will now be 13.0.0

This commit is contained in:
Ryan Ward 2018-09-26 13:02:19 -04:00
parent dfc75fa56c
commit 86845f4230
4 changed files with 213 additions and 121 deletions

View File

@ -1,9 +1,11 @@
Mulit Version: 12.3.0
Table of contents
-----------------
[TOC]
Multi static variables
------------------------
`multi.Version = "12.3.0"`
`multi.Version` -- The current version of the library
`multi.Priority_Core` -- Highest level of pirority that can be given to a process
`multi.Priority_High`
`multi.Priority_Above_Normal`
@ -14,9 +16,9 @@ Multi static variables
Multi Runners
-------------
multi:mainloop(**TABLE:** settings) -- This runs the mainloop by having its own internal while loop running
multi:threadloop(**TABLE:** settings) -- This runs the mainloop by having its own internal while loop running, but prioritizes threads over multi-objects
multi:uManager(**TABLE:** settings) -- This runs the mainloop, but does not have its own while loop and thus needs to be within a loop of some kind.
`multi:mainloop([TABLE settings])` -- This runs the mainloop by having its own internal while loop running
`multi:threadloop([TABLE settings])` -- This runs the mainloop by having its own internal while loop running, but prioritizes threads over multi-objects
`multi:uManager([TABLE settings])` -- This runs the mainloop, but does not have its own while loop and thus needs to be within a loop of some kind.
Multi Settings
--------------
@ -105,45 +107,43 @@ end
Multi constructors - Multi-Objs
-------------------------------
**Processors**
proc = multi:newProcessor(**STRING:** file [**nil**])
`proc = multi:newProcessor([STRING: file nil])`
**Non-Actors**
timer = multi:newTimer()
conn = multi:newConnection(**BOOLEAN:** protect [**true**])
nil = multi:newJob(**FUNCTION:** func, **STRING:** name)
range = multi:newRange()
cond = multi:newCondition(**FUNCTION:** func)
`timer = multi:newTimer()`
`conn = multi:newConnection([BOOLEAN protect true])`
`nil = multi:newJob(FUNCTION func, STRING name)`
`func = multi:newFunction(FUNCTION func)`
**Actors**
event = multi:newEvent(**FUNCTION:** task)
updater = multi:newUpdater(**NUMBER:** skip [**1**])
alarm = multi:newAlarm(**NUMBER:** [**0**])
loop = multi:newLoop(**FUNCTION:** func)
tloop = multi:newTLoop(**FUNCTION:** func ,**NUMBER:** set [**1**])
func = multi:newFunction(**FUNCTION:** func)
step = multi:newStep(**NUMBER:** start, **NUMBER:** reset, **NUMBER:** count [**1**], **NUMBER:** skip [**0**])
tstep = multi:newStep(**NUMBER:** start, **NUMBER:** reset, **NUMBER:** count [**1**], **NUMBER:** set [**1**])
trigger = multi:newTrigger(**FUNCTION:** func)
stamper = multi:newTimeStamper()
watcher = multi:newWatcher(**STRING** name)
watcher = multi:newWatcher(**TABLE** namespace, **STRING** name)
cobj = multi:newCustomObject(**TABLE** objRef, **BOOLEAN** isActor)
`event = multi:newEvent(FUNCTION task)`
`updater = multi:newUpdater([NUMBER skip 1])`
`alarm = multi:newAlarm([NUMBER 0])`
`loop = multi:newLoop(FUNCTION func)`
`tloop = multi:newTLoop(FUNCTION func ,NUMBER: [set 1])`
`step = multi:newStep(NUMBER start,*NUMBER reset, [NUMBER count 1], [NUMBER skip 0])`
`tstep = multi:newStep(NUMBER start, NUMBER reset, [NUMBER count 1], [NUMBER set 1])`
`trigger = multi:newTrigger(FUNCTION: func)`
`stamper = multi:newTimeStamper()`
`watcher = multi:newWatcher(STRING name)`
`watcher = multi:newWatcher(TABLE namespace, STRING name)`
`cobj = multi:newCustomObject(TABLE objRef, BOOLEAN isActor)`
Note: A lot of methods will return self as a return. This is due to the ability to chain that was added in 12.x.x
Processor
---------
proc = multi:newProcessor(**STRING:** file [**nil**])
`proc = multi:newProcessor([STRING file nil])`
Creates a processor runner that acts like the multi runner. Actors and Non-Actors can be created on these objects. Pausing a process pauses all objects that are running on that process.
An optional argument file is used if you want to load a file containing the processor data.
Note: This isn't portable on all areas where lua is used. Some interperters disable loadstring so it is not encouraged to use the file method for creating processors
loop = Processor:getController() -- returns the loop that runs the "runner" that drives this processor
**self** = Processor:Start() -- Starts the processor
**self** = Processor:Pause() -- Pauses the processor
**self** = Processor:Resume() -- Resumes a paused processor
nil = Processor:Destroy() -- Destroys the processor and all of the Actors running on it
`loop = Processor:getController()` -- returns the loop that runs the "runner" that drives this processor
`self = Processor:Start()` -- Starts the processor
`self = Processor:Pause()` -- Pauses the processor
`self = Processor:Resume()` -- Resumes a paused processor
`nil = Processor:Destroy()` -- Destroys the processor and all of the Actors running on it
Example
```lua
@ -174,23 +174,22 @@ Connections
-----------
Arguable my favorite object in this library, next to threads
conn = multi:newConnection(**BOOLEAN:** protect [**true**])
`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. **Deprecated**
returns or nil = conn:Fire(...) -- Triggers the connection with arguments ..., "returns" if non-nil is a table containing return values from the triggered connections.
**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** [**#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.
`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
`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**])
`link = conn(FUNCTION func, [STRING name nil], [NUMBER #conns+1])`
Example:
```lua
@ -239,11 +238,11 @@ OnCustomSafeEvent:Fire(1,100,"Hi Ya Folks!!!") -- fire them all again!!!
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
`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(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.
@ -273,8 +272,143 @@ print("There are "..multi:getJobs().." jobs in the queue!")
multi:mainloop()
```
Ranges
------
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:
```lua
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)
```
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()
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:
```lua
local multi = require("multi")
count=0
-- A loop object is used to demostrate how one could use an event object.
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:Destroy() -- destroys the loop from running!
print("Stopped that loop!",count)
end) -- events like alarms need to be reset the Reset() command works here as well
multi:mainloop()
```
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:
```lua
local multi = require("multi")
updater=multi:newUpdater(5000) -- simple, think of a loop with the skip feature of a step
updater:OnUpdate(function(self)
print("updating...")
end)
multi:mainloop()
```
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.
```lua
local multi = require("multi")
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()
```
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.
TLoops
------
`tloop = multi:newTLoop(FUNCTION func ,NUMBER: [set 1])`
Steps
-----
`step = multi:newStep(NUMBER start,*NUMBER reset, [NUMBER count 1], [NUMBER skip 0])`
TSteps
------
`tstep = multi:newStep(NUMBER start, NUMBER reset, [NUMBER count 1], [NUMBER set 1])`
Triggers
--------
`trigger = multi:newTrigger(FUNCTION: func)`
Time Stampers WIP
-----------------
`stamper = multi:newTimeStamper()`
Watchers
--------
`watcher = multi:newWatcher(STRING name)`
`watcher = multi:newWatcher(TABLE namespace, STRING name)`
Custom Objects
--------------
`cobj = multi:newCustomObject(TABLE objRef, BOOLEAN isActor)`
Coroutine based Threading
-------------------------
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. (Was ok, but only allowed for one pause of code ececution) Many objects were given threaded variants though, none are really needed since the base thread objects ant thread.* can be used to emulate those.
System Threads - Multi-core
---------------------------
Conditions
----------

View File

@ -1,17 +1,26 @@
#Changes
[TOC]
Update 12.3.0 So you documented it finally
Update 13.0.0 So you documented it, finally, but it's sad to see some things go isn't it?
-------------
Fixed: Tons of bugs, I actually went through the entire library and did a full test of everything while writing the documentation.
Changed: A few things to make things more clear when using the library
Changed:
- A few things to make things more clear when using the library
- The way functions returned paused status. Before it would return "PAUSED" now it returns nil, true if paused
Removed:
- Ranges and conditions -- corutine based threads can dmulate what these objects did and much better!
-
Added: ...
Update 12.2.2 Time for some more bug fixes!
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!
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!

View File

@ -24,8 +24,8 @@ SOFTWARE.
local bin = pcall(require,"bin")
local multi = {}
local clock = os.clock
multi.Version = "12.3.0"
multi._VERSION = "12.3.0"
multi.Version = "13.0.0"
multi._VERSION = "13.0.0"
multi.stage = "stable"
multi.__index = multi
multi.Mainloop = {}
@ -184,21 +184,6 @@ multi.GetParentProcess=multi.getParentProcess
function multi.Stop()
mainloopActive=false
end
function multi:condition(cond)
if not self.CD then
self:Pause()
self.held=true
self.CD=cond.condition
elseif not(cond.condition()) then
self.held=false
self:Resume()
self.CD=nil
return false
end
self.Parent:Do_Order()
return true
end
multi.Condition=multi.condition
function multi:isHeld()
return self.held
end
@ -281,6 +266,7 @@ function multi:IsAnActor()
end
function multi:OnMainConnect(func)
table.insert(self.func,func)
return self
end
function multi:reallocate(o,n)
n=n or #o.Mainloop+1
@ -321,7 +307,7 @@ function multi:connectFinal(func)
elseif self.Type=='step' or self.Type=='tstep' then
self:OnEnd(func)
else
print("Warning!!! "..self.Type.." doesn't contain a Final Connection State! Use "..self.Type..":Break(function) to trigger it's final event!")
print("Warning!!! "..self.Type.." doesn't contain a Final Connection State! Use "..self.Type..":Break(func) to trigger it's final event!")
self:OnBreak(func)
end
end
@ -369,7 +355,7 @@ function multi:SetTime(n)
self:Destroy()
end
end
return c
return self
end
multi.ResetTime=multi.SetTime
function multi:ResolveTimer(...)
@ -729,34 +715,7 @@ function multi.nextStep(func)
next[#self.next+1] = func
end
end
function multi:newRange()
local selflink=self
local temp={
getN = function(self) selflink:Do_Order() self.n=self.n+self.c if self.n>self.b then self.Link.held=false self.Link:Resume() return nil end return self.n end,
}
setmetatable(temp,{
__call=function(self,a,b,c)
self.c=c or 1
self.n=a-self.c
self.a=a
self.b=b
self.Link=selflink--.Parent.Mainloop[selflink.CID] or
self.Link:Pause()
self.Link.held=true
return function() return self:getN() end
end
})
self:create(temp)
return temp
end
multi.NewRange=multi.newRange
function multi:newCondition(func)
local c={['condition']=func,Type="condition"}
self:create(c)
return c
end
multi.OnPreLoad=multi:newConnection()
multi.NewCondition=multi.newCondition
--Core Actors
function multi:newCustomObject(objRef,isActor)
local c={}
@ -889,7 +848,12 @@ function multi:newFunction(func)
c.func=func
mt={
__index=multi,
__call=function(self,...) if self.Active then return self:func(...) end local t={...} return "PAUSED" end
__call=function(self,...)
if self.Active then
return self:func(...)
end
return nil,true
end
}
c.Parent=self
function c:Pause()

View File

@ -1,23 +1,8 @@
package.path="?/init.lua;?.lua;"..package.path
local multi = require("multi")
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!")
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()