core.base.thread
Provides native thread support for concurrent programming, including thread creation, synchronization primitives, and inter-thread communication.
thread.start
- Start a thread
Creates and starts a thread to execute a callback function.
local t = thread.start(callback_function, ...)
Parameters: callback
callback function to execute in the thread, ...
additional arguments passed to the callback function
Return Value: Returns a thread object that can be used to wait for thread completion
NOTE
Each thread is a separate Lua VM instance, their Lua variable states are completely isolated and cannot be directly shared. Parameters are passed unidirectionally and internally serialized, therefore only support serializable parameters like string
, table
, number
, etc.
thread.start_named
- Start a named thread
Creates and starts a new thread with the specified name and callback function.
local t = thread.start_named("thread_name", callback_function, ...)
Parameters: name
thread name, callback
callback function to execute in the thread, ...
additional arguments passed to the callback function
Return Value: Returns a thread object that can be used to wait for thread completion
NOTE
Parameters are passed unidirectionally and internally serialized, therefore only support serializable parameters like string
, table
, number
, etc.
Example
import("core.base.thread")
function callback(id)
import("core.base.thread")
print("%s: %d starting ..", thread.running(), id)
for i = 1, 10 do
print("%s: %d", thread.running(), i)
os.sleep(1000)
end
print("%s: %d end", thread.running(), id)
end
function main()
local t0 = thread.start_named("thread_0", callback, 0)
local t1 = thread.start_named("thread_1", callback, 1)
t0:wait(-1)
t1:wait(-1)
end
thread.running
- Get the current thread name
Returns the name of the currently running thread.
local name = thread.running()
Return Value
Returns the name of the current thread as a string.
thread.mutex
- Create a mutex object
Creates a new mutex for thread synchronization.
local mutex = thread.mutex()
Return Value: Returns a mutex object with the following methods: mutex:lock()
lock the mutex, mutex:unlock()
unlock the mutex
NOTE
Mutex can be accessed across threads for inter-thread synchronization.
Example
import("core.base.thread")
function callback(mutex)
import("core.base.thread")
print("%s: starting ..", thread.running())
for i = 1, 10 do
mutex:lock()
print("%s: %d", thread.running(), i)
mutex:unlock()
os.sleep(1000)
end
print("%s: end", thread.running())
end
function main()
local mutex = thread.mutex()
local t0 = thread.start_named("thread_0", callback, mutex)
local t1 = thread.start_named("thread_1", callback, mutex)
t0:wait(-1)
t1:wait(-1)
end
thread.event
- Create an event object
Creates a new event for thread signaling and synchronization.
local event = thread.event()
Parameters: timeout
timeout in milliseconds (-1 for infinite wait)
Return Value: Returns an event object with the following methods: event:wait(timeout)
wait for the event to be signaled, event:post()
signal the event
NOTE
Event object can be accessed across threads for inter-thread signaling.
Example
import("core.base.thread")
function callback(event)
import("core.base.thread")
print("%s: starting ..", thread.running())
while true do
print("%s: waiting ..", thread.running())
if event:wait(-1) > 0 then
print("%s: triggered", thread.running())
end
end
end
function main()
local event = thread.event()
local t = thread.start_named("keyboard", callback, event)
while true do
local ch = io.read()
if ch then
event:post()
end
end
t:wait(-1)
end
thread.semaphore
- Create a semaphore object
Creates a new semaphore for thread synchronization and resource counting.
local semaphore = thread.semaphore(name, initial_count)
Parameters: name
semaphore name, initial_count
initial count value
Return Value: Returns a semaphore object with the following methods: semaphore:wait(timeout)
wait for semaphore (decrement count), semaphore:post(count)
post to semaphore (increment count)
NOTE
Semaphore can be accessed across threads for inter-thread resource counting and synchronization.
Example
import("core.base.thread")
function callback(semaphore)
import("core.base.thread")
print("%s: starting ..", thread.running())
while true do
print("%s: waiting ..", thread.running())
if semaphore:wait(-1) > 0 then
print("%s: triggered", thread.running())
end
end
end
function main()
local semaphore = thread.semaphore("", 1)
local t = thread.start_named("keyboard", callback, semaphore)
while true do
local ch = io.read()
if ch then
semaphore:post(2)
end
end
t:wait(-1)
end
thread.queue
- Create a thread-safe queue object
Creates a new thread-safe queue for inter-thread data communication.
local queue = thread.queue()
Return Value: Returns a queue object with the following methods: queue:push(value)
push a value to the queue, queue:pop()
pop a value from the queue, queue:empty()
check if the queue is empty
NOTE
Queue is the primary way for inter-thread data communication and supports cross-thread access.
Example
import("core.base.thread")
function callback(event, queue)
print("starting ..")
while true do
print("waiting ..")
if event:wait(-1) > 0 then
while not queue:empty() do
print(" -> %s", queue:pop())
end
end
end
end
function main()
local event = thread.event()
local queue = thread.queue()
local t = thread.start_named("", callback, event, queue)
while true do
local ch = io.read()
if ch then
queue:push(ch)
event:post()
end
end
t:wait(-1)
end
thread.sharedata
- Create a shared data object
Creates a new shared data object for inter-thread data sharing.
local sharedata = thread.sharedata()
Return Value: Returns a shared data object with the following methods: sharedata:set(value)
set the shared data value, sharedata:get()
get the shared data value
NOTE
Shared data object is the primary way for inter-thread data sharing and supports cross-thread access.
Example
import("core.base.thread")
function callback(event, sharedata)
print("starting ..")
while true do
print("waiting ..")
if event:wait(-1) > 0 then
print(" -> %s", sharedata:get())
end
end
end
function main()
local event = thread.event()
local sharedata = thread.sharedata()
local t = thread.start_named("", callback, event, sharedata)
while true do
local ch = io.read()
if ch then
sharedata:set(ch)
event:post()
end
end
t:wait(-1)
end
thread:wait
- Wait for thread completion (thread instance method)
Waits for the thread to complete execution. This method supports mixed scheduling with coroutines, allowing you to wait for thread completion within a coroutine.
thread:wait(timeout)
Parameters: timeout
timeout in milliseconds (-1 for infinite wait)
Return Value: Returns a status code indicating the wait result
Example (Mixed Thread and Coroutine Scheduling)
import("core.base.thread")
import("core.base.scheduler")
function thread_loop()
import("core.base.thread")
print("%s: starting ..", thread.running())
for i = 1, 10 do
print("%s: %d", thread.running(), i)
os.sleep(1000)
end
print("%s: end", thread.running())
end
function coroutine_loop()
print("%s: starting ..", scheduler.co_running())
for i = 1, 10 do
print("%s: %d", scheduler.co_running(), i)
os.sleep(1000)
end
print("%s: end", scheduler.co_running())
end
function main()
scheduler.co_start_named("coroutine", coroutine_loop)
local t = thread.start_named("thread", thread_loop)
t:wait(-1) -- Wait for thread completion in coroutine
end