In a multi-threaded application dealing with events comming in a random way, it is mandatory to share data between threads but also to manage a to-do list of actions to be done in the main thread. As an example, when an MQTT message arrives, its dedicated thread will validate and present incoming data but update of the graphical display has to be centralised to avoid glitches and make resources management easier.

Séléné's SelShared manages a list of tasks to be launched, a list that can be feed by as many as needed threads in a secure way as explained in this page.

This full source code of examples can be found here.

First of all, lets create 2 test functions

function test()
        print("test()")
end

function test2()
        print("test2()")
end

and push them in the stack.

SelShared.PushTask( test ) 
SelShared.PushTask( test2 ) 

Stack's content can be displayed using SelShared.dump() function.

Initial stack
---------------
List f:(nil) l:(nil)
Pending tasks : 0 / 2
        1 2

First lesson : references to tasks are pushed which are simply an integer (1, 2, ...) and not the function name. Don't forget functions in Lua are simply banal objects, nothing more ; it permit usage of unnamed function

SelShared.PushTask( function () print'toto' end )

Now, our repository holds 3 functions

List f:(nil) l:(nil)
Pending tasks : 0 / 3
        1 2 3

1. test()
2. test2()
3. a unamed one.

Test is already in the stack, lets push it again

SelShared.PushTask( test )
SelShared.dump()

and the result is

List f:(nil) l:(nil)
Pending tasks : 0 / 3
        1 2 3

by default, if a task in not pushed again in the waiting list if it is already present. This behaviour can be changed by passing an additional argument to SelShared.PushTask()

SelShared.PushTask( test, SelShared.TaskOnceConst("ONCE")

The default behaviour, as said, the function is not added if already present in the stack.

List f:(nil) l:(nil)
Pending tasks : 0 / 4
        1 2 3 1

SelShared.PushTask( test, SelShared.TaskOnceConst("MULTIPLE"))

The same tasks may be present several time in the stack.

List f:(nil) l:(nil)
Pending tasks : 0 / 4
        1 2 3 1

As you can see, function #1 is present at the first place and has been pushed again at the end.

SelShared.PushTask( test, SelShared.TaskOnceConst("LAST"))

Any reference to the function already present in the stack is made invalid (-1 or 0xffffffff) and then a new one is pushed at the end.

List f:(nil) l:(nil)
Pending tasks : 0 / 5
        ffffffff 2 3 ffffffff 1

In all above examples, tasks registration is done implicitly. But it's also possible to register ourself and then submit a task as the following

local ref=SelShared.RegisterFunction( test )
print( "Register ID for test() : " .. ref )
print( SelShared.PushTaskByRef( ref, SelShared.TaskOnceConst("MULTIPLE") ) 

Register ID for test() : 1

List f:(nil) l:(nil)
Pending tasks : 0 / 6
        ffffffff 2 3 ffffffff 1 1

As you can see in this example, as 'test' function as been already registered during previous tests, the function returns 1 : you can have only one reference per function.

Tasks in the stack are launched sequentially, in First In / First Out order at each WaitFor() call, using this kind of loop

while true do
        local rt = table.pack( Selene.WaitFor( )
        for _,ret in ipairs(rt) do
                if type(ret) == 'function' then
                        ret()
                end
        end
end

If a task is waiting, WaitFor() will return it, otherwise, it will block until a task is added or another event occurs. Please have a look on WaitFor() dedicated page for more explanation and warnings regarding launched tasks.