imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li

2026-08-24T08:08:27Z

Imported from legacy OpenComputers documentation at ocdoc.cil.li

New page

= Thread(线程) API =

Thread(线程) API为OpenOS提供了协程的一种变体。线程比基础的协程在很多方面都更高级，并且对很多工作流程而言都更易用。OpenOS线程是自主的，非阻塞的，可分离的进程。

* '''自主性：'''线程在创建后会立即开始异步执行，无需调用resume。与协程不同，线程在yield后会自恢复，且不会回到创建线程的代码行。使用协程进行编程基于用户显式进行的协作yield和resume调用。然而，在线程中yield或调用`event.pull`，只会暂时阻塞线程，线程将自行继续运行。

* '''非阻塞性：'''线程可以调用`computer.pullSignal`（或其更高级别的包装，如`event.pull`、`io.pull`等），而不会阻塞主内核进程或任何其他线程。当然线程本身会被阻塞，直到出现信号或超时。线程的计算流程与在命令行中运行相同的代码一样。在幕后，thread(线程)库使用`pullSignal`在线程之间切换，并在适当的时候唤醒线程。这与协程完全不同，在协程中，`computer.pullSignal`会阻塞系统上的所有其他活动，直到出现信号或超时。

* '''可分离性：'''默认情况下，线程由创建它们的进程拥有（注意线程本身就是一个进程）。拥有线程的进程被称为其父进程。父进程关闭（即执行完毕）时会关闭所有正在运行的子线程（将子线程join到父进程）。但是在以下情况下，进程不必关闭线程：

* 线程从父进程上分离。参见`t:detach()`。请注意线程也可以附着于其他父进程，参见`t:attach()`。

* 父进程抛出了异常或调用了`os.exit`，此时所有附着在上面的线程都会被杀死。请注意，重启也会杀死所有线程。

* 线程被杀死，参见`t:kill()`。

* 线程被手动暂停，参见`t:suspend()`。

=== 独立事件注册 ===

每个线程都维护了一套独立的事件注册机制；不继承也不分享。线程中创建的所有事件注册记录（即侦听器或定时器）都只从属于此线程。

* 线程结束时，其所有事件注册记录都会随之结束。
* `suspended`（暂停的）线程会忽略事件（参见`t:status() suspended`）
* 一个线程不可以访问/移除/交互其他线程的事件注册记录。
* 被推送的事件对系统中的所有运行中线程可见。
* 两个独立的线程可以对同一个事件`event.pull`，每个线程都会独立观测到此事件。

== 概述 ==

线程主要有两种用途是其他选择无法提供：

* 你需要编写一个函数，其中进行了阻塞式调用，但不阻塞程序其它部分的运行。 - 你需要编写长期运行的后台函数，而不想手动管理其yield与resum。

== 函数 ==

此处定义了两类API。

1. [[API/thread/zh#线程API|线程]]API，或者说静态函数，由`require("thread")`提供。 2. [[API/thread/zh#线程句柄API|线程句柄]]API，或者说适用于`thread.create`创建的线程_对象_的api。在此文档中这些线程句柄将会仅以`t`表示。

== 线程API ==

* `thread.create(thread_proc: function[, ...]): table`

<pre>开启一个执行函数`thread_proc`的新线程，并返回其线程句柄，参见[[API/thread/zh#线程句柄API|线程句柄API]]。此方法可接收可选的`...`参数，这些参数将会被传递给`thread_proc`。线程将自动开始运行。
</pre>
```lua local thread = require("thread") print("Main program start") thread.create(function(a, b)

<pre>print(a)
os.sleep()
print(b)
</pre>
end, 'A', 'B') print("Main program end") ```

输出： ``` Main program start A Main program end B ```

* `thread.waitForAll(threads: table[, timeout: number]): boolean, string`

<pre>等待给出的`threads`全部执行完成。此阻塞式操作可以在给出的`timeout`秒超时时间后返回，若给出此值的话。返回值为是否成功，若失败还会返回报错信息。线程可以在多种条件下被认定为”执行完成“，详见`t:join()`。
</pre>
```lua local thread = require("thread") print("Main program start") local t = thread.create(function(a, b)

<pre>print(a)
os.sleep()
print(b)
</pre>
end, 'A', 'B') thread.waitForAll({t}) print("Main program end") ```

输出： ``` Main program start A B Main program end ```

* `thread.waitForAny(threads: table[, timeout: number): boolean, string`

<pre>等待给出线程中的某一个完成，其他方面`thread.waitForAll()`一致。
</pre>
```lua local thread = require("thread") print("Main program start") local t1 = thread.create(function(a, b)

<pre>print(a)
os.sleep()
print(b)
</pre>
end, 'A', 'B') local t2 = thread.create(function(c, d)

<pre>print(c)
os.sleep()
os.sleep()
print(d)
</pre>
end, 'C', 'D') thread.waitForAny({t1, t2}) print("Main program end") ```

输出： ``` Main program start A C B Main program end D ```

请注意线程恢复的顺序并未指定，此样例中也有可能在输出"Main program end"之前就输出"D"。

* `thread.current(): table`

<pre>返回当前线程对象`t`。init进程不代表任何线程，此函数在init进程内而且不在任何线程内调用时不会有返回值。
</pre>
== 线程句柄API ==

* `t:resume(): boolean, string`

<pre>恢复（或者说解冻）一个暂停的线程。返回操作是否成功，若失败额外返回一条报错信息。线程在创建时直接就是运行状态，因此在基本的线程工作流程中完全用不到调用`t:resume()`。“运行中”的线程会自动继续，直到执行完毕。只有在需要恢复被暂停的（`t:suspend()`）线程时才需要`t:resume()`。**请注意，**因为你不是直接恢复线程，线程抛出的一切异常都会被线程运行库吸收，不会暴露给你的进程。
</pre>
* 目前还无法为线程挂载异常处理函数，但是现在可以用`event.onError`将报错信息输出到"/tmp/event.log"。请注意目前硬中断异常只会抛出一次，并且在抛出硬中断时，带线程的进程执行的行为仍未指定。目前，任何一个线程或父进程都可能接收到异常。这些细节并不是线程规范的一部分，任何实现细节的部分都可能在以后发生变化。

* `t:suspend(): boolean, string`

<pre>暂停（或者说冻结）一个运行中的线程。返回操作是否成功，若失败额外返回一条报错信息。“暂停的”线程不会自动唤醒，也不会随其父进程（若附有的话）结束而结束。暂停的线程会忽略出现的事件，代表此线程中定义的任何事件侦听器和定时器都不会响应事件通知。请注意线程不会缓存事件信号，暂停的线程可能会错失其等待的信号。例如，假设一个线程最近一次使用了`event.pull("modem_message")`等待信号，并且被“暂停”了，此时电脑收到了一条"modem_message"。这样线程将错失事件，永远不知道发生了什么。请注意如果你暂停了一条正在被阻塞以等待事件的线程，线程下次被唤醒时会接收到什么事件是未指定的。

暂停当前线程就会导致线程立刻yield，在其他地方显式调用`t:resume()`之前也不会恢复。
</pre>
'''`t:resume`和`t:suspend`的特别注释'''

不要把这两个方法当作`coroutine.resume()`和`coroutine.yield()`。这两个方法是间接的，而且线程是独自异步开始或停止运行的。请将这一特性与协程方法相对比，协程方法是直接的，而且会立即唤起或离开协程的执行。参考这些样例：

```lua local thread = require("thread") local t -- 此样例需要t的upvalue t = thread.create(function()

<pre>print("start")
thread.current():suspend()
print("after suspend")
os.sleep()
print("after sleep")
</pre>
end) ```

输出： ``` start ```

```lua local thread = require("thread") local t -- this example needs an upvalue to t t = thread.create(function()

<pre>print("start")
thread.current():suspend()
print("after suspend")
os.sleep()
print("after sleep")
</pre>
end) print("outside thread create") t:resume() print("after resume") ```

输出： ``` start outside thread create after suspend after resume after sleep ```

* `t:kill()`

<pre>给它一刀！将线程杀死。线程将会被终止，不能再继续执行其线程函数。它的所有事件注册记录也都会随之结束。请注意核心底层实际上是Lua协程，协程不是抢占式线程。因此线程的结束点是可知的，意味着你可以预测线程结束的准确位置。参考此样例：
</pre>
```lua local thread = require("thread") local t = thread.create(function()

<pre>while true do
print("running")
print("still running")
os.sleep()
print("after sleep")
end
print("unreachable code")
</pre>
end) print("before kill") t:kill() print("after kill") ```

输出： ``` running still running before kill after kill ```

* `t:status(): string`

<pre>以字符串形式返回线程状态。
</pre>
* '''"running" 运行'''

<pre>运行中的线程会在yield和阻塞式调用后继续运行（自动重新开始活动），直到其线程函数退出。这是创建后线程的初始与默认状态。线程就算在阻塞或不活动的状态下也会保持“运行”状态。运行中的线程可以被暂停（`t:suspend()`）或杀死（`t:kill()`），但是不可以恢复（`t:resume()`）。运行中的线程将会阻塞`t:join()`的调用，也会阻塞其父进程的关闭。与协程不同，协程在未执行时即为“暂停”状态，而线程就算在等待事件时也是“运行”状态。
</pre>
* '''"suspended" 暂停'''

<pre>被暂停的线程会保持暂停状态，永远不会自动恢复执行其线程函数。暂停的线程会在其附着的父进程关闭时或你试图`t:join()`它时自动被杀死。暂停的线程会忽略事件信号，此线程的上下文所创建的，或其创建的任何子线程所创建的事件注册记录，也都会忽略事件信号。暂停线程的子线程表现会与暂停一样，即使其状态为“运行”。暂停的线程可以恢复（`t:resume()`）或者杀死（`t:kill()`），但不可以暂停（`t:suspend()`）。
</pre>
* '''"dead" 死亡'''

<pre>死亡的线程是结束了或放弃了自己的运行或被终止的线程。它不可被恢复（`t:resume()`）也不可被暂停（`t:suspend()`）。死亡的线程不会阻塞父进程的关闭。杀死死亡的线程不会报错，而是什么也不做。
</pre>
** 状态样例 **

```lua local thread = require("thread") local t = thread.create(function()

<pre>print("before sleep")
os.sleep()
print("after sleep")
</pre>
end) print(t:status()) ```

输出： ``` before sleep running after sleep ```

```lua local thread = require("thread") local t = thread.create(function()

<pre>print("before sleep")
os.sleep()
print("after sleep")
</pre>
end) t:suspend() print(t:status()) os.sleep(10) print(t:status()) t:resume() print("after resume") print(t:status()) ```

输出： ``` before sleep suspended suspended after resume dead ```

* `t:attach([level: number]): boolean, string`

<pre>将一个线程附着到一个进程，通常称为子线程或附着线程。`level`为可选参数，可用于获取父进程，传递0或`nil`则使用当前运行进程。在最初创建线程时，线程已经被附着于当前进程。若`level`指向了不存在的线程，则此方法会返回`nil`与一条报错信息，否则返回true。附着的线程将会阻塞其父进程的关闭，直到线程死亡（或者被杀死，或者父进程放弃执行）。

</pre>
* `t:detach(): table, string`

<pre>将一个线程从其父进程（若有）上解除附着。若未执行动作则返回`nil`与一条报错信息，否则返回自身（以便于你想在同一行中创建一个线程并将其解除附着）。解除附着的线程会继续执行，直到电脑关机或重启，或者线程死亡。
</pre>
```lua local detached_thread = thread.create(function() end):detach() ```

* `t:join([timeout: number]): boolean, string`

<pre>阻塞调用者，直到`t`不再运行。或者在到达了`timeout`秒的超时时间后返回`false`（可选）。在`t:join()`的调用结束后线程的状态将为“死亡”。任一下列情况都会导致`join`结束并停止阻塞调用者：
</pre>
* 线程继续运行，直到其从线程函数中返回。
* 线程被放弃，或抛出了未被捕获的异常。
* 线程被暂停。
* 线程被杀死

<pre>调用`thread.waitForAll({t})`在功能上与调用`t:join()`一致。在进程结束时会对其子线程调用`thread.waitForAll`（若有）。子线程也通过同样的机制阻塞其父进程。
</pre>
== 线程异常样例 ==

此样例演示了线程抛出异常时会发生什么。线程在抛出未捕获的异常时会停止执行并进入“死亡”状态。报错信息将不会输出到stdout或stderr（详见`t:resume()`）。

```lua local thread = require("thread") local tty = require("tty")

print("p start") local reader = thread.create(function()

<pre>print("reader start")
error("thread abort") -- 抛出一个异常
print("reader done")
</pre>
end) print("p end", reader:status()) ```

输出： ``` p start reader start p end dead ```

== 线程中断处理函数样例 ==

此样例演示了你该如何注册处理软中断（^c）的函数，用于关闭文件句柄、释放资源等等，然后退出整个程序。

```lua local thread = require("thread") local event = require("event")

local cleanup_thread = thread.create(function()

<pre>event.pull("interrupted")
print("cleaning up resources")
</pre>
end)

local main_thread = thread.create(function()

<pre>print("main program")
while true do
io.write("input: ")
io.read()
end
</pre>
end)

thread.waitForAny({cleanup_thread, main_thread}) os.exit(0) -- 关闭所有剩余线程 ```

假设用户按下了^c发送了一次软中断

输出： ``` main program input: ^c cleaning up resources ```

== 非阻塞式线程Yield/Pull操作样例 ==

此样例演示了现在OpenOS可支持非阻塞式线程。

```lua local event = require("event") local thread = require("thread") thread.create(function()

<pre>a,b,c,d,e,f,g = coroutine.yield()
print(a,b,c,d,e,f,g)
print(event.pull())
</pre>
end)

event.push("custom_event_a") print("done") event.push("custom_event_b", 2) ```

输出： ``` custom_event_a done custom_event_b 2 ```

== 目录 ==

{{:API/contents/zh}}

API/thread/zh - Revision history

imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li