Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
Next revision Both sides next revision
api:thread:zh [2022/08/11 10:49]
fight_xing created 		api:thread:zh [2023/10/20 11:38]
hfsr [Thread API]
Line 1: Line 1:
-====== Thread API ======+====== Thread(线程) ​API ====== 
 +Thread(线程) API为OpenOS提供了协程的一种变体。线程比基础的协程在很多方面都更高级，并且对很多工作流程而言都更易用。OpenOS线程是自主的，非阻塞的，可分离的进程。
  
-**本篇文章的部分/​全部内容还没有进行翻译。**+* **自主性：**线程在创建后会立即开始异步执行，无需调用resume。与协程不同，线程在yield后会自恢复，且不会回到创建线程的代码行。使用协程进行编程基于用户显式进行的协作yield和resume调用。然而，在线程中yield或调用`event.pull`，只会暂时阻塞线程，线程将自行继续运行。
  
-The Thread API provides a variation of coroutines for openos. A thread is superior to basic coroutines in many ways and, for many workflows, is easier to work with. An openos thread is an autonomous non-blocking detachable process. 
  
-* **Autonomous**: Threads asynchronously begin execution immediately after creation without needing to call resume. Unlike coroutines, threads self-resume after yielding and do not yield back to the line of code where they were created. Programming with coroutines builds on the cooperative yield and resume calls made explicitly by the user. Yielding or calling ​`event.pull` ​from a thread, however, only temporarily blocks just that thread and will continue on its own.+* **非阻塞性：**线程可以调用`computer.pullSignal`（或其更高级别的包装，如`event.pull`、`io.pull`等），而不会阻塞主内核进程或任何其他线程。当然线程本身会被阻塞，直到出现信号或超时。线程的计算流程与在命令行中运行相同的代码一样。在幕后，thread(线程)库使用`pullSignal`在线程之间切换，并在适当的时候唤醒线程。这与协程完全不同，在协程中，`computer.pullSignal`会阻塞系统上的所有其他活动，直到出现信号或超时。
  
  
-* **Non-Blocking**: Threads can call `computer.pullSignal` (or any higher level wrapper such as `event.pull`,​ `io.pull`, etc) without blocking the main kernel process nor any other thread. The thread itself is blocked until a signal or timeout occurs. The computational flow of the thread behaves just as if the same code were run in a script from the command line. Behind the scenes, the thread library is using pullSignal to swap between threads, and waking threads up when appropriate. This is very much unlike coroutines where `computer.pullSignal` blocks all other activity on the system until a signal or timeout occurs.+* **可分离性：**默认情况下，线程由创建它们的进程拥有（注意线程本身就是一个进程）。拥有线程的进程被称为其父进程。父进程关闭（即执行完毕）时会关闭所有正在运行的子线程（将子线程join到父进程）。但是在以下情况下，进程不必关闭线程：
  
 +  * 线程从父进程上分离。参见`t:​detach()`。请注意线程也可以附着于其他父进程，参见`t:​attach()`。
  
-* **Detachable**:​ By default, threads are owned by the process in which they are created (note that threads themselves are a process). The owning process is known as the parent process. When a parent process is closing (i.e. it has reached the end of its execution) it will close(i.e. join) all of its running child threads. A process does not have to close a thread when:+  ​* 父进程抛出了异常或调用了`os.exit`，此时所有附着在上面的线程都会被杀死。请注意，重启也会杀死所有线程。
  
 +  * 线程被杀死，参见`t:​kill()`。
  
-  * The thread detaches from the parent process. see `t:detach()`. Note that a thread can also attach to another parent. see `t:attach()`+  * 线程被手动暂停，参见`t:suspend()`。
  
-  * The parent process throws an exception or calls `os.exit` in which case all attached threads are killed. Note that rebooting also kills all threads.+====独立事件注册====
  
-  ​* The thread is killed. see `t:kill()`+每个线程都维护了一套独立的事件注册机制；不继承也不分享。线程中创建的所有事件注册记录（即侦听器或定时器）都只从属于此线程。 
 +  * 线程结束时，其所有事件注册记录都会随之结束。 
 +  ​* `suspended`（暂停的）线程会忽略事件（参见`t:status() suspended`） 
 +  * 一个线程不可以访问/​移除/​交互其他线程的事件注册记录。 
 +  * 被推送的事件对系统中的所有运行中线程可见。 
 +  * 两个独立的线程可以对同一个事件`event.pull`，每个线程都会独立观测到此事件。 
 +===== 概述 =====
  
-  * The thread is manually suspended. see `t:​suspend()`+线程主要有两种用途是其他选择无法提供：
  
-====Event Registration Independence====+- 你需要编写一个函数，其中进行了阻塞式调用，但不阻塞程序其它部分的运行。 
 +- 你需要编写长期运行的后台函数，而不想手动管理其yield与resum。
  
-A thread maintains an independent set of event registrations;​ it does not inherit any and it does not share any. Any event registration made (e.g. listeners or timers) inside a thread belongs to that thread. +===== 函数 ​=====
-  * When a thread dies all of its event registrations die with it. +
-  * A `suspended` thread ignores events (see `t:status() suspended`) +
-  * A thread cannot access/​remove/​interfere with another thread'​s event registrations. +
-  * A pushed event is observed by all running threads on the system. +
-  * Two separate threads can `event.pull` for the same event, and each thread will observe the event independently. +
-===== Overview ​=====+
  
-There are two main use cases for using threads over other viable options+此处定义了两类API。
  
-- You want to write a function that makes blocking calls without blocking the rest of your application. +1. [[api:​thread:​zh#​线程API|线程]]API，或者说静态函数，由`require("​thread"​)`提供。 
-- You want a long running background function without having to manage yielding and resuming it manually.+2. [[api:​thread:​zh#​线程句柄API|线程句柄]]API，或者说适用于`thread.create`创建的线程_对象_的api。在此文档中这些线程句柄将会仅以`t`表示。
  
-===== Functions ===== +===== 线程API =====
- +
-There are two sections of API defined here. +
- +
-1. The [[api:​thread#​Thread_API|thread]] api, or the static functions, provided by `require("​thread"​)` +
-2. The [[api:​thread#​Thread_Handle_API|thread handle]] api, or the api available the thread _objects_ created by `thread.create`. In this documentation these thread handles will be denoted by just `t`. +
- +
-===== Thread ​API =====+
  
 - `thread.create(thread_proc:​ function[, ...]): table` - `thread.create(thread_proc:​ function[, ...]): table`
  
-  ​Starts a new thread executing the function ​`thread_proc` ​and returns its thread handle, see [[api:​thread#​Thread_Handle_API|Thread Handle ​API]]. This method takes an optional ​`...` which is passed to `thread_proc`. The runtime of the thread continues autonomously.+  ​开启一个执行函数`thread_proc`的新线程，并返回其线程句柄，参见[[api:​thread:zh#线程句柄API|线程句柄API]]。此方法可接收可选的`...`参数，这些参数将会被传递给`thread_proc`。 线程将自动开始运行。
  
 ```lua ```lua
Line 61: Line 57:
 ``` ```
  
-Output:+输出：
 ``` ```
 Main program start Main program start
Line 71: Line 67:
 - `thread.waitForAll(threads:​ table[, timeout: number]): boolean, string` - `thread.waitForAll(threads:​ table[, timeout: number]): boolean, string`
  
-  ​Waits for the array of `threads` ​to complete. This blocking call can return in `timeout` ​seconds if provided. Returns success and an error message on failure. A thread is "​completed"​ under multiple conditions, see `t:​join()` ​for details.+  ​等待给出的`threads`全部执行完成。此阻塞式操作可以在给出的`timeout`秒超时时间后返回，若给出此值的话。返回值为是否成功，若失败还会返回报错信息。线程可以在多种条件下被认定为”执行完成“，详见`t:join()`。
  
 ```lua ```lua
Line 85: Line 81:
 ``` ```
  
-Output:+输出：
 ``` ```
 Main program start Main program start
Line 95: Line 91:
 - `thread.waitForAny(threads:​ table[, timeout: number): boolean, string` - `thread.waitForAny(threads:​ table[, timeout: number): boolean, string`
  
-  ​Waits for any single thread to complete and is otherwise equivalent to `thread.waitForAll()`+  ​等待给出线程中的某一个完成，其他方面`thread.waitForAll()`一致。
  
 ```lua ```lua
Line 115: Line 111:
 ``` ```
  
-Output:+输出：
 ``` ```
 Main program start Main program start
Line 125: Line 121:
 ``` ```
  
-Please note that threads resume order is not specified and this example may print "​D"​ before it prints ​"Main program end"+请注意线程恢复的顺序并未指定，此样例中也有可能在输出"Main program end"之前就输出"​D"​。
  
 - `thread.current():​ table` - `thread.current():​ table`
  
-  ​Returns the current thread ​`t` object. The init process does not represent a thread and nothing is returned from this method if called from the init process and not inside any thread.+  ​返回当前线程对象`t`。init进程不代表任何线程，此函数在init进程内而且不在任何线程内调用时不会有返回值。