local tasks=require("wetgenes.tasks").create()

Manage tasks that should be performed on seperate threads so as not to block the main thread.

Manage coroutines that can then easily call into these threads by yeilding

tasks:add_global_thread(thread)

This runs an add_thread inside a named thread so all threads are kept together no matter which thread tried to start it.

thread is the same as add_thread

if the thread id already exists then it will not be added again.

tasks:add_id(it)

Internal function to manage creation of all objects with unique ids.

local memo=tasks:add_memo({})

Create a memo with a unique auto generated numerical id for linda comunication.

local thread=tasks:add_task({
    id="test",
    code=function(linda,task_id,task_idx,task)
        while true do
            local _,memo= linda:receive( 0 , task_id )
            if memo then
                ...
            end
        end
    end,
})

Create a task with various preset values similar to a thread except inside a coroutine on the calling thread. As this function is inside a coroutine you must yield regulary this yield will then continue on the next update. Probably called once ever 60th of a second.

id

A unique id string to be used by lindas when sending messages into this task. The function is expected to sit in an infinite loop testing this linda socket and then yielding if there is nothing to do.

count

The number of tasks to create, they will all use the same instanced code function so should be interchangable and it should not matter which task we are actually running code on. If you expect the task to maintain some state between memos, then this must be 1 .

code

A lua function to run inside a coroutine, this function will recieve tasks.linda (which is a colinda) and the task.id for comunication and an index so we know which of the count tasks we are (mostly for debugging) and finally the task table itself which make sense to share with coroutines.

local thread=tasks:add_thread({
    id="test",
    count=1,
    code=function(linda,task_id,task_idx)
        while true do
            local _,memo= linda:receive( nil , task_id )
            if memo then
                ...
            end
        end
    end,
})

Create a thread with various preset values:

id

A unique id string to be used by lindas when sending messages into this task. The function is expected to sit in an infinite loop waiting on this linda socket.

count

The number of threads to create, they will all use the same instanced code function so should be interchangable and it should not matter which thread we are actually running code on. If you expect the task to maintain some state between memos, then this must be 1 .

code

A lua function to run inside each thread, this function will recieve tasks.linda and the task.id for comunication and an index so we know which of the count threads we are (mostly for debugging)

tasks:claim_global(name,value)

Claim a name using the global linda socket, returns value on success or false on failure.

The value will be associated with the name on success.

This will block waiting on a result but should be fast.

Send and/or recieve a (web)socket client memo result.

returns nil,error if something went wrong or returns result if something went right.

A basic function to handle (web)socket client connection.

require("wetgenes.tasks").cocall(f1,f2,...)
require("wetgenes.tasks").cocall({f1,f2,...})

Manage simple coroutines that can poll each others results and wait on them.

Turn a table of "setup" functions into a table of coroutines that can yield waiting for other coroutines to complete and run them all.

You still need to be carefull with race conditions but it allows you to write code in such away that setup order is no longer important. Setup functions can coroutine.yield waiting for another setup to finish first.

Create a tasks group to contain all associated threads and coroutines along with their comunications.

local colinda=require("wetgenes.tasks").colinda(linda)

Create a colinda which is a wrapper around a linda providing replacement functions to be used inside a coroutine so it will yield (and assume it will be resumed) rather than wait.

This should be a dropin replacement for a linda and will fallback to normal linda use if not in a coroutine.

If linda is nil then we will create one, the linda used in this colinda can be found in colinda.linda if you need raw access.

What we are doing here is wrapping the send/receive functions so that

colinda:send(time,...)
colinda:recieve(time,...)

will be replaced with functions that call

linda:send(0,...)
linda:recieve(0,...)

and use coroutines.yield to mimic the original timeout value without blocking.

tasks:del_global_thread({id="threadname"})

Destroy a given thread.id or all the threads if thread is nil.

tasks:del_id(it)

Internal function to manage deletion of all objects with unique ids.

tasks:del_memo(memo)

Delete a memo.

tasks:del_task(task)

Delete a task.

tasks:del_thread(thread)

Delete a thread.

tasks:delete()

Force stop all threads and delete all data.

Failure to call this will allow any created threads to continue to run until program termination.

result = tasks:do_memo(memo,timeout)
result = tasks:do_memo(memo)

Similar to calling tasks:receive but without the problems that come from me trying to remember how to spell receive and it returns memo.result instead of memo so slightly less mess. This will assert on finding a memo.error so less need to check for errors.

tasks:eject_global(name)

Eject a name using the global linda socket, returns value associated with name on success or false on failure.

The value will no longer be associated with the name when this succeeds.

This will block waiting on a result but should be fast.

tasks:fetch_global(name)

Fetch value associated with the name using the global linda socket or false on failure. You can not associated nil or false with a global value.

This will block waiting on a result but should be fast.

A basic function to handle global memos to get/set data shared amongst multiple tasks.

Create send and return a http memo result.

Returns either the result or nil,error so can be used simply with an assert wrapper.

A basic function to handle http memos.

memo = tasks:receive(memo,timeout)
memo = tasks:receive(memo)

Recieve a memo with optional timeout.

This is intended to be run from within a coroutine task on the main thread. It will work outside of a task but that will block the main thread waiting for a response.

The memo will be deleted after being recieved (ie we will have called del_memo) so as to free up its comunication id for another memo.

if the memo has not yet been sent or even been through add_memo (we check state for "setup" or nil) then it will be autosent with the same timeout before we try and receive it.

After calling check if memo.error is nil then you will find the result in memo.result

tasks:run_task(task)

Resume all the coroutines in this task.

Any errors will be logged with a backtrace.

If the tasks have finished running (returned or crashed) then we will tasks:del_task(task) this task. Check task.id which will be nil after this task has finished.

memo = tasks:send(memo,timeout)
memo = tasks:send(memo)

Send a memo with optional timeout.

This is intended to be run from within a coroutine task on the main thread. It will work outside of a task but that may block the main thread waiting to send.

if memo.id is not set then we will auto call add_memo to create it.

Check memo.error for posible error, this will be nil if everything went OK.

Create send and return a sqlite memo result.

Returns either the result.rows or nil,error so can be used simply with an assert wrapper.

Note that rows can be empty so an additional assert(rows[1]) might be needed to check you have data returned.

A basic function to handle sqlite memos.

As we are opening an sqlite database here it wont help much to have more than one thread per database as they will just fight over file access.

Handle global tasks, starting and stopping and preventing the starting of multiple copies of the same task.

tasks:update()

Resume all current coroutines and wait for them to yield.