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

Function Prototype

::: tip API

thread.start(callback: <function>, ...)

:::

Parameter Description

Parameter	Description
callback	Required. Callback function to execute in the thread
...	Optional. Additional arguments passed to the callback function

Usage

Creates and starts a thread to execute a 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

Function Prototype

::: tip API

thread.start_named(name: <string>, callback: <function>, ...)

:::

Parameter Description

Parameter	Description
name	Required. Thread name
callback	Required. Callback function to execute in the thread
...	Optional. Additional arguments passed to the callback function

Usage

Creates and starts a new thread with the specified name and 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

Function Prototype

::: tip API

thread.running()

:::

Parameter Description

No parameters required for this function.

Usage

Returns the name of the currently running thread.

Returns the name of the current thread as a string.

thread.mutex

• Create a mutex object

Function Prototype

::: tip API

thread.mutex()

:::

Parameter Description

No parameters required for this function.

Usage

Creates a new mutex for thread synchronization.

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

Function Prototype

::: tip API

thread.event()

:::

Parameter Description

No parameters required for this function.

Usage

Creates a new event for thread signaling and synchronization.

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

Function Prototype

::: tip API

thread.semaphore(name: <string>, initial_count: <number>)

:::

Parameter Description

Parameter	Description
name	Required. Semaphore name
initial_count	Required. Initial count value

Usage

Creates a new semaphore for thread synchronization and resource counting.

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

Function Prototype

::: tip API

thread.queue()

:::

Parameter Description

No parameters required for this function.

Usage

Creates a new thread-safe queue for inter-thread data communication.

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

Function Prototype

::: tip API

thread.sharedata()

:::

Parameter Description

No parameters required for this function.

Usage

Creates a new shared data object for inter-thread data sharing.

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)

Function Prototype

::: tip API

thread:wait(timeout: <number>)

:::

Parameter Description

Parameter	Description
timeout	Required. Timeout in milliseconds (-1 for infinite wait)

Usage

Waits for the thread to complete execution. This method supports mixed scheduling with coroutines, allowing you to wait for thread completion within a coroutine.

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