xmake-docs/docs/api/scripts/extension-modules/core/base/thread.md

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

::: tip 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

::: tip 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

::: tip 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

::: tip 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)

::: tip 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

::: tip 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

::: tip 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