语法指南 | 优宽量化

内置函数

结构体

内置变量

Threads

优宽量化交易平台从系统底层真正支持JavaScript语言策略的多线程功能，实现了以下对象：

对象	说明	备注
threading	多线程全局对象	成员函数：`Thread`、`getThread`、`mainThread`等。
Thread	线程对象	成员函数：`peekMessage`、`postMessage`、`join`等。
ThreadLock	线程锁对象	成员函数：`acquire`、`release`。可作为线程执行函数的参数传入线程环境。
ThreadEvent	事件对象	成员函数：`set`、`clear`、`wait`、`isSet`。可作为线程执行函数的参数传入线程环境。
ThreadCondition	条件对象	成员函数：`notify`、`notifyAll`、`wait`、`acquire`、`release`。可作为线程执行函数的参数传入线程环境。
ThreadDict	字典对象	成员函数：`get`、`set`。可作为线程执行函数的参数传入线程环境。

threading

threading对象作为全局多线程管理工具，提供了创建并发线程、线程锁、条件对象等功能。本章节介绍threading对象的成员函数。仅JavaScript语言策略支持该对象。

Thread

Thread()函数用于创建并发线程。


    
    
    
Thread(func, ...args)


    
    
    
Thread(...items)

示例

同时创建一个自定义函数和一个匿名函数的并发线程。


    javascript
    
    
function test1(a, b, c) {
    Log("test1:", a, b, c)
}

function main() {
    var t1 = threading.Thread(test1, 1, 2, 3)
    var t2 = threading.Thread(function (msg) {
        Log("msg:", msg)
    }, "Hello thread2")

    t1.join()
    t2.join()
}

使用Thread(...items)形式创建并发线程，按顺序执行多个函数。


    javascript
    
    
function test1(msg) {
    Log("msg:", msg)
    test2("Hello test2")
}

function main() {
    var t1 = threading.Thread(
        [function(a, b, c) {Log(a, b, c)}, 1, 2, 3],
        [test1, "Hello test1"],
        [`function test2(msg) {Log("msg:", msg)}`])

    t1.join()
}

支持向并发执行函数的参数中传入函数。


    javascript
    
    
function testFunc1(p) {
    Log("testFunc1 p:", p)
}

function main() {
    threading.Thread(function(pfn) {
        var threadName = threading.currentThread().name()
        var threadId = threading.currentThread().id()
        pfn(`in thread threadName: ${threadName}, threadId: ${threadId}`)
    }, testFunc1).join()
}

支持传入函数字符串，可动态导入外部库进行并发计算。


    javascript
    
    
function ml(input) {
    const net = new brain.NeuralNetwork()
    net.train([
        { input: [0, 0], output: [0] },
        { input: [0, 1], output: [1] },
        { input: [1, 0], output: [1] },
        { input: [1, 1], output: [0] },
    ])
    return net.run(input)
}

function main() {
    var ret = threading.Thread([ml, [1, 0]], [HttpQuery("https://unpkg.com/brain.js")]).join()

    // ret: {"id":1,"terminated":false,"elapsed":337636000,"ret":{"0":0.9339330196380615}}
    Log(ret)
}

返回值

类型	描述
`Thread`对象	`Thread()`函数返回一个`Thread`对象，用于管理创建的并发线程、线程通信等。

参数

名称	类型	必填	描述
func	function	是	参数`func`是用于并发执行的函数（通过引用传递），支持传入匿名函数。`func`可接受多个参数，这些参数将在并发执行时通过`...args`传入。因此，`func`的参数列表需要与`...args`保持一致。
arg	string / number / bool / object / array / function / any (系统支持的所有类型)	否	参数`arg`是在回调执行时传递给`func`（即并发线程执行函数）的实际参数；参数`arg`可以有多个，`func`的参数列表需要与`...args`保持一致。
item	array	是	参数`item`是一个数组，包含待并发执行的函数引用及其参数。调用`Thread`函数时，参数`item`可以传入多组。

参考

getThread mainThread currentThread Lock Condition Event Dict pending eventLoop

备注

传入Thread()函数用于并发执行的线程函数func运行在隔离环境中，因此无法直接引用线程外部的变量，引用时会导致编译失败。同时，线程内不支持引用其他闭包函数。线程内部可以调用平台提供的所有API，但不能调用用户自定义的其他函数。

当线程执行完毕且没有被持续引用时，系统底层会自动回收线程相关的资源，无需显式调用join()函数来释放资源。如果存在持续引用导致无法释放资源，当并发数量超过2000个时会报错：InternalError: too many routine wait, max is 2000。

支持回测系统、实盘环境。所有并发线程相关的函数在回测系统中仅作为代码兼容性支持，实际不会真正执行并发线程，本章不再赘述。

getThread

getThread()函数用于根据指定的线程ID获取线程对象。


    
    
    
getThread(threadId)

示例

通过threadId获取指定的线程对象。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function () {
        // Thread 对象有方法：id()，用于获取线程的Id，可以查看文档对应Thread对象的章节
        var id = threading.currentThread().id()
        var thread1 = threading.getThread(id)

        Log("id:", id, ", thread1.id():", thread1.id())
        Log(`id == thread1.id():`, id == thread1.id())
    })
    t1.join()
}

返回值

类型	描述
`Thread`对象	`getThread()`函数返回由参数threadId指定的`Thread`对象

参数

名称	类型	必填	描述
threadId	number	是	参数`threadId`为线程对象ID，通过指定该参数获取对应的线程对象。

参考

Thread mainThread currentThread Lock Condition Event Dict pending eventLoop

备注

支持回测系统、实盘环境。

如果目标线程已经执行完毕并被释放，则无法通过threading.getThread(threadId)获取该线程的线程对象。

mainThread

mainThread()函数用于获取主线程的线程对象，即策略中main()函数所在的线程。


    
    
    
mainThread()

示例

获取主线程的Thread对象，输出主线程的threadId。


    javascript
    
    
function main() {
    Log("主线程的threadId：", threading.mainThread().id())
}

在并发线程中获取主线程的线程对象。


    javascript
    
    
function test() {
    Log("test函数中输出主线程Id：", threading.mainThread().id())
}

function main() {
    var t1 = threading.Thread(test)
    t1.join()
}

返回值

类型	描述
`Thread`对象	`mainThread()`函数返回主线程的线程对象。

参考

getThread Thread currentThread Lock Condition Event Dict pending eventLoop

备注

支持回测系统、实盘环境。

currentThread

currentThread()函数用于获取当前线程的线程对象。


    
    
    
currentThread()

示例

获取当前线程的Thread对象，输出当前线程的threadId。


    javascript
    
    
function test() {
    Log("当前线程的Id：", threading.currentThread().id())
}

function main() {
    var t1 = threading.Thread(test)
    t1.join()
}

返回值

类型	描述
`Thread`对象	`currentThread()`函数返回当前线程的线程对象。

参考

Thread mainThread Thread Lock Condition Event Dict pending eventLoop

备注

支持回测系统、实盘环境。

Lock

Lock()函数用于创建线程锁对象。


    
    
    
Lock()

示例

两个并发线程访问共享资源。


    javascript
    
    
function consumer(productionQuantity, dict, lock) {
    for (var i = 0; i < productionQuantity; i++) {
        lock.acquire()
        var count = dict.get("count")
        Log("consumer:", count)
        Sleep(1000)
        lock.release()
    }
}

function producer(productionQuantity, dict, lock) {
    for (var i = 0; i < productionQuantity; i++) {
        lock.acquire()
        dict.set("count", i)
        Log("producer:", i)
        Sleep(1000)
        lock.release()
    }
}

function main() {
    var dict = threading.Dict()
    dict.set("count", -1)
    var lock = threading.Lock()
    var productionQuantity = 10
    var producerThread = threading.Thread(producer, productionQuantity, dict, lock)
    var consumerThread = threading.Thread(consumer, productionQuantity, dict, lock)

    consumerThread.join()
    producerThread.join()
}

返回值

类型	描述
`ThreadLock`对象	`Lock()`函数返回一个线程锁对象。

参考

getThread mainThread currentThread Thread Condition Event Dict pending eventLoop

备注

支持回测系统、实盘环境。

Condition

Condition()函数用于创建条件变量对象，该对象在多线程并发环境中实现线程间的同步与通信。通过Condition()，线程可以在特定条件未满足时进入等待状态，直到其他线程发出条件满足的通知。


    
    
    
Condition()

示例

两个并发线程访问共享资源。


    javascript
    
    
function consumer(productionQuantity, dict, condition) {
    for (var i = 0; i < productionQuantity; i++) {
        condition.acquire()
        while (dict.get("array").length == 0) {
            condition.wait()
        }
        var arr = dict.get("array")
        var count = arr.shift()
        dict.set("array", arr)
        Log("consumer:", count, ", array:", arr)
        condition.release()
        Sleep(1000)
    }
}

function producer(productionQuantity, dict, condition) {
    for (var i = 0; i < productionQuantity; i++) {
        condition.acquire()
        var arr = dict.get("array")
        arr.push(i)
        dict.set("array", arr)
        Log("producer:", i, ", array:", arr)
        condition.notify()
        condition.release()
        Sleep(1000)
    }
}

function main() {
    var dict = threading.Dict()
    dict.set("array", [])
    var condition = threading.Condition()
    var productionQuantity = 10
    var producerThread = threading.Thread(producer, productionQuantity, dict, condition)
    var consumerThread = threading.Thread(consumer, productionQuantity, dict, condition)
    consumerThread.join()
    producerThread.join()
}

返回值

类型	描述
`ThreadCondition`对象	`Condition()`函数返回一个`ThreadCondition`对象。

参考

getThread mainThread currentThread Lock Thread Event Dict pending eventLoop

备注

回测系统暂不支持此功能，仅提供接口定义。

Event

Event()函数用于创建一个线程事件对象，该对象用于线程间的同步，允许一个线程等待另一个线程的通知或信号。


    
    
    
Event()

示例

两个并发线程访问共享资源。


    javascript
    
    
function consumer(productionQuantity, dict, pEvent, cEvent) {
    for (var i = 0; i < productionQuantity; i++) {
        while (dict.get("array").length == 0) {
            pEvent.wait()
        }
        if (pEvent.isSet()) {
            pEvent.clear()
        }

        var arr = dict.get("array")
        var count = arr.shift()
        dict.set("array", arr)
        Log("consumer:", count, ", array:", arr)
        cEvent.set()
        Sleep(1000)
    }
}

function producer(productionQuantity, dict, pEvent, cEvent) {
    for (var i = 0; i < productionQuantity; i++) {
        while (dict.get("array").length != 0) {
            cEvent.wait()
        }
        if (cEvent.isSet()) {
            cEvent.clear()
        }

        var arr = dict.get("array")
        arr.push(i)
        dict.set("array", arr)
        Log("producer:", i, ", array:", arr)
        pEvent.set()
        Sleep(1000)
    }
}

function main() {
    var dict = threading.Dict()
    dict.set("array", [])
    var pEvent = threading.Event()
    var cEvent = threading.Event()
    var productionQuantity = 10
    var producerThread = threading.Thread(producer, productionQuantity, dict, pEvent, cEvent)
    var consumerThread = threading.Thread(consumer, productionQuantity, dict, pEvent, cEvent)

    consumerThread.join()
    producerThread.join()
}

返回值

类型	描述
`ThreadEvent`对象	`Event()`函数返回一个`ThreadEvent`对象。

参考

getThread mainThread currentThread Lock Condition Thread Dict pending eventLoop

备注

支持回测系统、实盘环境。

Dict

Dict()函数用于创建一个字典对象，用于在并发线程间传递数据。


    
    
    
Dict()

示例

向并发线程执行函数传入普通对象，测试修改对象键值后是否会影响其他线程中的对象键值。


    javascript
    
    
function threadFun1(obj) {
    obj["age"] = 100
    while (true) {
        Log("threadFun1 obj:", obj)
        Sleep(5000)
    }
}

function threadFun2(obj) {
    while (true) {
        Log("threadFun2 obj:", obj)
        Sleep(5000)
    }
}

function main() {
    var obj = {"age": 10}
    var t1 = threading.Thread(threadFun1, obj)
    var t2 = threading.Thread(threadFun2, obj)
    t1.join()
    t2.join()
}

向并发线程执行函数传入Dict()函数创建的ThreadDict对象，测试修改对象键值后是否会影响其他线程中的对象键值。


    javascript
    
    
function threadFun1(threadDict) {
    threadDict.set("age", 100)
    while (true) {
        Log(`threadFun1 threadDict.get("age"):`, threadDict.get("age"))
        Sleep(5000)
    }
}

function threadFun2(threadDict) {
    while (true) {
        Log(`threadFun2 threadDict.get("age"):`, threadDict.get("age"))
        Sleep(5000)
    }
}

function main() {
    var threadDict = threading.Dict()
    threadDict.set("age", 10)
    var t1 = threading.Thread(threadFun1, threadDict)
    var t2 = threading.Thread(threadFun2, threadDict)

    t1.join()
    t2.join()
}

返回值

类型	描述
`ThreadDict`对象	`Dict()`函数返回一个`ThreadDict`对象。

参考

getThread mainThread currentThread Lock Condition Event Thread pending eventLoop

备注

向并发线程函数传入普通对象时采用深拷贝方式传递，在并发线程中修改键值不会影响其他线程中的字典。

支持回测系统、实盘环境。

pending

pending函数用于获取当前策略程序中正在运行的并发线程数量。


    
    
    
pending()

示例

创建两个并发运行的线程，并在不同时间点调用pending()函数。


    javascript
    
    
function threadFun1() {
    Log("threadFun1")
    Sleep(3000)
}

function threadFun2() {
    for (var i = 0; i < 3; i++) {
        LogStatus(_D(), "print from threadFun2")
        Sleep(3000)
    }
}

function main() {
    Log(`begin -- threading.pending():`, threading.pending())

    var t1 = threading.Thread(threadFun1)
    var t2 = threading.Thread(threadFun2)
    Log(`after threading.Thread -- threading.pending():`, threading.pending())

    t1.join()
    t2.join()
    Log(`after thread.join -- threading.pending():`, threading.pending())
}

返回值

类型	描述
number	`pending()`函数返回当前策略程序中正在运行的并发线程数量。

参考

getThread mainThread currentThread Lock Condition Event Dict Thread eventLoop

备注

当策略main()函数开始运行时直接调用pending()函数将返回1，这是因为策略main()函数所在的主线程本身也被计入正在运行的线程中。

支持回测系统和实盘环境。

Thread

Thread对象可以通过threading.Thread()、threading.getThread()、threading.mainThread()、threading.currentThread()创建或返回。

peekMessage

peekMessage()函数用于从线程接收消息。


    
    
    
peekMessage()


    
    
    
peekMessage(timeout)

示例

并发线程向主线程发送消息。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        for (var i = 0; i < 10; i++) {
            Log("thread1 postMessage():", i)
            threading.mainThread().postMessage(i)
            Sleep(500)
        }
    })

    while (true) {
        var msg = threading.currentThread().peekMessage()
        Log("main peekMessage():", msg)
        if (msg == 9) {
            break
        }
        Sleep(1000)
    }

    t1.join()
}

返回值

类型	描述
string / number / bool / object / array / any (系统支持的所有类型)	`peekMessage()`函数返回当前线程对象关联的线程接收到的消息。

参数

名称	类型	必填	描述
timeout	number	否	参数`timeout`为超时设置，按照该参数设置的毫秒数阻塞等待并返回数据；若无数据且超时则返回空值。如果`timeout`设置为0或不传`timeout`参数，则一直阻塞等待，直到接收到通道中的数据。如果`timeout`设置为-1，则不阻塞并立即返回数据，无数据时返回空值。

参考

postMessage join terminate getData setData id name eventLoop

备注

编写程序时需注意避免线程死锁问题。

postMessage

postMessage()函数用于向线程发送消息。


    
    
    
postMessage(msg)

示例

在并发线程中发送消息，使用eventLoop()接收消息通知。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        for (var i = 0; i < 10; i++) {
            Log("thread1 postMessage():", i)
            threading.mainThread().postMessage(i)
            Sleep(500)
        }
    })
    for (var i = 0; i < 10; i++) {
        var event = threading.mainThread().eventLoop()
        Log("main event:", event)
        Sleep(500)
    }
    t1.join()
}

支持发送函数。


    javascript
    
    
function main() {
    threading.mainThread().postMessage(function(msg) {
        Log("func from mainThread, msg:", msg)
    })

    threading.Thread(function() {
        var func = threading.mainThread().peekMessage()
        func("in " + threading.currentThread().name())
    }).join()
}

参数

名称	类型	必填	描述
msg	string / number / bool / object / array / function / any (系统支持的所有类型)	是	参数`msg`为要发送的消息。

参考

peekMessage join terminate getData setData id name eventLoop

备注

当线程的执行函数中调用postMessage()函数发送信号或数据时，会产生消息事件。可以使用eventLoop()函数接收消息通知。

join

join()函数用于等待线程退出并回收系统资源。


    
    
    
join()


    
    
    
join(timeout)

示例

测试join()函数超时并输出返回值。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        Log("Hello thread1")
        Sleep(5000)
    })

    var ret = t1.join(1000)
    Log("ret:", ret)   // ret: undefined

    ret = t1.join()
    Log("ret:", ret)   // ret: {"id":1,"terminated":false,"elapsed":5003252000}
}

返回值

类型描述

ThreadRet对象

ThreadRet对象包含执行结果的相关数据，包含以下属性：

id: 线程ID。
terminated: 线程是否被强制终止。
elapsed: 线程的运行时间（纳秒）。
ret: 线程函数的返回值。

参数

名称	类型	必填	描述
timeout	number	否	`timeout`参数用于设置等待线程结束的超时时间，单位为毫秒。当`timeout`参数设置为0或不设置`timeout`参数时，`join()`函数会阻塞等待，直到线程执行结束。当`timeout`参数设置为-1时，`join()`函数会立即返回。

参考

peekMessage postMessage terminate getData setData id name eventLoop

备注

join()函数超时时返回undefined。

terminate

terminate()函数用于强制终止线程，释放该线程占用的硬件资源。


    
    
    
terminate()

示例

强制终止一个线程的执行。线程被强制终止后，日志中将不再输出该线程的内容。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        for (var i = 0; i < 10; i++) {
            Log("thread1 i:", i)
            Sleep(1000)
        }
    })

    Sleep(3000)
    t1.terminate()
    Log("after t1.terminate()")

    while (true) {
        LogStatus(_D())
        Sleep(1000)
    }
}

参考

peekMessage postMessage join getData setData id name eventLoop

备注

对于使用terminate()函数强制终止的线程，无法再使用join()函数等待其结束。

getData

getData()函数用于访问线程环境中记录的变量。数据在线程未执行join()函数（等待退出成功）且未执行terminate()函数（强制终止线程）的情况下有效。


    
    
    
getData()


    
    
    
getData(key)

示例

在并发线程的环境中记录键名为count的值，然后在主线程中读取count的键值。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        for (var i = 0; i < 5; i++) {
            threading.currentThread().setData("count", i)
            Log(`setData("count"):`, i)
            Sleep(1000)
        }
    })
    for (var i = 0; i < 5; i++) {
        var count = threading.getThread(t1.id()).getData("count")
        Log(`getData("count"):`, count)
        Sleep(1000)
    }
    t1.join()
}

返回值

类型	描述
string / number / bool / object / array / any (系统支持的所有类型)	`getData()`函数返回当前线程环境中存储的键值对中`key`参数对应的键值。

参数

名称	类型	必填	描述
key	string	是	`key`参数为存储的键值对的键名。

参考

peekMessage postMessage join terminate setData id name eventLoop

setData

setData()函数用于在线程环境中存储变量。


    
    
    
setData(key, value)

示例

在并发线程中设置键值对，在主线程中读取该键值对。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        threading.currentThread().setData("data", 100)
    })
    Sleep(1000)
    Log(`t1.getData("data"):`, t1.getData("data"))
    t1.join()
}

支持将函数作为键值传入。


    javascript
    
    
function main() {
    threading.mainThread().setData("func2", function(p) {
        Log("func2 p:", p)
    })

    var t1 = threading.Thread(function() {
        threading.currentThread().setData("func1", function(p) {
            Log("func1 p:", p)
        })

        var func2 = threading.mainThread().getData("func2")
        func2("test2")
    })

    Sleep(1000)
    var func1 = t1.getData("func1")
    func1("test1")
    t1.join()
}

参数

名称	类型	必填	描述
key	string	是	`key`参数用于指定存储的键值对的键名。
value	string / number / bool / object / array / function / any (系统支持的所有类型)	是	`value`参数用于指定存储的键值对的键值。

参考

peekMessage postMessage join terminate getData id name eventLoop

备注

数据在线程未执行join()函数（等待退出成功）且未执行terminate()函数（强制终止线程）的情况下有效。参数value的值必须是可序列化的变量。

id

id()函数用于返回当前多线程对象实例的threadId。


    
    
    
id()

示例

创建一个并发线程，在主线程中输出该并发线程的threadId。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        threading.currentThread().setData("data", 100)
    })
    Log(`t1.id():`, t1.id())
    t1.join()
}

返回值

类型	描述
number	`id()`函数返回当前线程的`threadId`。

参考

peekMessage postMessage join terminate getData setData name eventLoop

name

name()函数用于返回当前多线程对象实例的名称。


    
    
    
name()

示例

创建一个并发运行的线程，在主线程中输出该并发线程的名称。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        threading.currentThread().setData("data", 100)
    })
    Log(`t1.name():`, t1.name())  // t1.name(): Thread-1
    t1.join()
}

返回值

类型	描述
string	`name()`函数返回并发线程的名称。

参考

peekMessage postMessage join terminate getData setData id eventLoop

eventLoop

eventLoop()函数用于监听线程接收到的事件。


    
    
    
eventLoop()


    
    
    
eventLoop(timeout)

示例

并发执行3个线程，输出接收到的事件信息。超时或立即返回时输出空值。


    javascript
    
    
function main() {
    var t1 = threading.Thread(function() {
        while (true) {
            var eventMsg = threading.currentThread().eventLoop()     // 阻塞等待
            // 2024-11-14 10:14:18 thread1 eventMsg: {"Seq":1,"Event":"thread","ThreadId":0,"Index":1,"Queue":0,"Nano":1731550458699947000}
            Log(_D(), "thread1 eventMsg:", eventMsg)
        }
    })

    var t2 = threading.Thread(function() {
        while (true) {
            var eventMsg = threading.currentThread().eventLoop(-1)   // 立即返回
            Log(_D(), "thread2 eventMsg:", eventMsg)
            Sleep(5000)
        }
    })

    var t3 = threading.Thread(function() {
        while (true) {
            var eventMsg = threading.currentThread().eventLoop(3000) // 设置3秒超时
            Log(_D(), "thread3 eventMsg:", eventMsg)
        }
    })

    t1.postMessage("Hello ", t1.name())
    t2.postMessage("Hello ", t2.name())
    t3.postMessage("Hello ", t3.name())
    t1.join()
    t2.join()
    t3.join()
}

返回值

类型	描述
object / 空值	`eventLoop()`函数返回当前线程接收到的事件信息，详见事件信息结构。

参数

名称	类型	必填	描述
timeout	number	否	参数`timeout`为超时设置，单位为毫秒。参数`timeout`如果设置为0则阻塞等待直到有事件发生才返回；如果大于0则设置事件等待超时时间；如果小于0则立即返回最近的事件。

参考

peekMessage postMessage join terminate getData setData id name

备注

eventLoop()函数的处理机制与全局函数EventLoop()一致。

ThreadLock

线程锁对象，用于多线程同步处理。

acquire

acquire()函数用于请求线程锁（加锁）。


    
    
    
acquire()

示例

示例请参考threading.Lock()章节的内容。

参考

Lock release

备注

acquire()函数用于请求线程锁。当线程调用某个线程锁对象的acquire()函数时，它会尝试获取该锁。如果锁当前未被其他线程占用，调用线程将成功获得锁并继续执行。如果锁已被其他线程持有，调用acquire()的线程将被阻塞，直到锁被释放。

release

release()函数用于释放线程锁（解锁）。


    
    
    
release()

示例

测试死锁场景


    javascript
    
    
function consumer(productionQuantity, dict, pLock, cLock) {
    for (var i = 0; i < productionQuantity; i++) {
        pLock.acquire()
        cLock.acquire()
        var arr = dict.get("array")
        var count = arr.shift()
        dict.set("array", arr)
        Log("consumer:", count, ", array:", arr)
        cLock.release()
        Sleep(1000)
        pLock.release()
    }
}

function producer(productionQuantity, dict, pLock, cLock) {
    for (var i = 0; i < productionQuantity; i++) {
        cLock.acquire()   // cLock.acquire() 放在 pLock.acquire() 后不会产生死锁
        pLock.acquire()
        var arr = dict.get("array")
        arr.push(i)
        dict.set("array", arr)
        Log("producer:", i, ", array:", arr)
        pLock.release()
        Sleep(1000)
        cLock.release()
    }
}

function main() {
    var dict = threading.Dict()
    dict.set("array", [])
    var pLock = threading.Lock()
    var cLock = threading.Lock()
    var productionQuantity = 10
    var producerThread = threading.Thread(producer, productionQuantity, dict, pLock, cLock)
    var consumerThread = threading.Thread(consumer, productionQuantity, dict, pLock, cLock)

    consumerThread.join()
    producerThread.join()
}

参考

Lock acquire

备注

需要注意，线程锁使用不当可能导致死锁。

ThreadEvent

事件对象，用于多线程间的事件通知和信号传递。

set

set()函数用于触发事件（设置信号）。


    
    
    
set()

示例

请参考threading.Event()章节中的示例。

参考

clear wait isSet

备注

如果信号已经通过set()设置，则不能重复设置，需要先清除信号后才能重新设置。

clear

clear()函数用于清除信号。


    
    
    
clear()

示例

请参考threading.Event()章节中的示例。

参考

set wait isSet

wait

wait()函数用于设置事件（信号）等待，在事件（信号）被设置之前会阻塞；支持设置超时参数。


    
    
    
wait()


    
    
    
wait(timeout)

示例

测试wait()函数的返回值。


    javascript
    
    
function main() {
    var event = threading.Event()
    var t1 = threading.Thread(function(event) {
        var ret = event.wait(100)
        Log(`event.wait(100):`, ret)
        ret = event.wait()
        Log(`event.wait():`, ret)
    }, event)

    Sleep(1000)
    event.set()
    t1.join()
}

返回值

类型	描述
bool	`wait()`函数返回是否超时，如果发生超时则返回真值。

参数

名称	类型	必填	描述
timeout	number	否	参数`timeout`用于设置等待超时时间，单位为毫秒。

参考

set clear isSet

isSet

isSet()函数用于判断事件（信号）是否已被设置。


    
    
    
isSet()

示例

请参考threading.Event()章节中的示例。

返回值

类型	描述
bool	`isSet()`函数返回事件（信号）的设置状态；如果事件（信号）已被设置，则返回真值。

参考

set clear wait

ThreadCondition

条件变量对象，用于实现多线程间的同步与通信。

notify

notify()函数用于唤醒一个正在等待的线程（如果存在）。只有调用了wait()方法的线程才能被唤醒。


    
    
    
notify()

示例

使用notify()函数唤醒等待中的线程。


    javascript
    
    
function consumer(dict, condition) {
    while (true) {
        condition.acquire()
        while (dict.get("array").length == 0) {
            Log(threading.currentThread().name(), "wait()...", ", array:", dict.get("array"))
            condition.wait()
        }
        var arr = dict.get("array")
        var num = arr.shift()
        Log(threading.currentThread().name(), ", num:", num, ", array:", arr, "#FF0000")
        dict.set("array", arr)
        Sleep(1000)
        condition.release()
    }
}

function main() {
    var condition = threading.Condition()
    var dict = threading.Dict()
    dict.set("array", [])
    var t1 = threading.Thread(consumer, dict, condition)
    var t2 = threading.Thread(consumer, dict, condition)
    var t3 = threading.Thread(consumer, dict, condition)
    Sleep(1000)
    var i = 0
    while (true) {
        condition.acquire()
        var msg = ""
        var arr = dict.get("array")
        var randomNum = Math.floor(Math.random() * 5) + 1
        if (arr.length >= 3) {
            condition.notifyAll()
            msg = "notifyAll"
        } else {
            arr.push(i)
            dict.set("array", arr)
            if (randomNum > 3 && arr.length > 0) {
                condition.notify()
                msg = "notify"
            } else {
                msg = "pass"
            }
            i++
        }

        Log(_D(), "randomNum:", randomNum, ", array:", arr, ", msg:", msg)
        condition.release()
        Sleep(1000)
    }
}

参考

notifyAll wait acquire release

备注

notify()函数会唤醒等待队列中的一个线程。

notify()函数唤醒线程时，该线程会重新获取线程锁。

notifyAll

notifyAll()函数用于唤醒所有正在等待的线程。


    
    
    
notifyAll()

示例

示例请参考ThreadCondition.notify()章节的内容。

参考

notify wait acquire release

备注

notifyAll()函数会逐个唤醒所有处于等待状态的线程，被唤醒的线程将重新尝试获取线程锁。

wait

wait()函数用于在特定条件下使线程进入等待状态。


    
    
    
wait()

示例

示例请参考ThreadCondition.notify()章节的内容。

参考

notify notifyAll acquire release

备注

wait()函数会释放线程锁，当线程被唤醒时会重新获取线程锁。

acquire

acquire()函数用于请求线程锁（加锁）。


    
    
    
acquire()

示例

示例请参考ThreadCondition.notify()章节的内容。

参考

notify notifyAll wait release

备注

在调用wait()之前必须先请求当前条件对象的线程锁（加锁）。

release

release()函数用于释放线程锁（解锁）。


    
    
    
release()

示例

示例请参考ThreadCondition.notify()章节的内容。

参考

notify notifyAll wait acquire

备注

在调用wait()之后需要释放当前条件对象的线程锁（解锁）。

ThreadDict

线程安全的字典对象，用于在多线程环境中进行数据共享。

get

get()函数用于获取字典对象中记录的键值。


    
    
    
get(key)

示例

使用事件对象通知线程读取和修改数据。


    javascript
    
    
function main() {
    var event = threading.Event()
    var dict = threading.Dict()
    dict.set("data", 100)

    var t1 = threading.Thread(function(dict, event) {
        Log(`thread1, dict.get("data"):`, dict.get("data"))

        event.set()
        event.clear()

        event.wait()
        Log(`after main change data, thread1 dict.get("data"):`, dict.get("data"))

        dict.set("data", 0)
    }, dict, event)

    event.wait()

    dict.set("data", 99)

    event.set()
    event.clear()

    t1.join()
    Log(`main thread, dict.get("data"):`, dict.get("data"))
}

返回值

类型	描述
string / number / bool / object / array / any (系统支持的所有类型)	`get()`函数返回参数`key`指定的键对应的值。

参数

名称	类型	必填	描述
key	string	是	参数`key`用于指定要获取的键名。

参考

set

set

set()函数用于设置键值对。


    
    
    
set(key, value)

示例

支持将函数作为键值传入。


    javascript
    
    
function main() {
    var dict1 = threading.Dict()
    dict1.set("func1", function(p) {
        Log("func1 p:", p)
    })

    threading.Thread(function(dict1) {
        var func1 = dict1.get("func1")
        func1("test")
    }, dict1).join()
}

参数

名称	类型	必填	描述
key	string	是	参数`key`用于指定需要设置的键名。
value	string / number / bool / object / array / function / any (系统支持的所有类型)	是	参数`value`用于指定需要设置的键值。

参考

get