This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
api:thread [2017/09/07 19:30] payonel [Thread Handle API] |
api:thread [2017/12/02 10:03] payonel [Event Registration Independence] |
||
|---|---|---|---|
| Line 2: | Line 2: | ||
| 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. | 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 continue on its own. | + | * **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. |
| Line 19: | Line 19: | ||
| * The thread is manually suspended. see `t:suspend()` | * The thread is manually suspended. see `t:suspend()` | ||
| + | ====Event Registration Independence==== | ||
| + | |||
| + | 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. | ||
| ===== Overview ===== | ===== Overview ===== | ||
| Line 138: | Line 145: | ||
| **Special notes about `t:resume`, `t:suspend`** | **Special notes about `t:resume`, `t:suspend`** | ||
| - | Do not think of these methods as `coroutine.resume()` nor `coroutine.yield()`. These methods are indirect and a thread will asynchronously start or stop running on its own. Contrast this to coroutine methods which directly and immediately invoke execution or leave execution of a coroutine. Consider this example: | + | Do not think of these methods as `coroutine.resume()` nor `coroutine.yield()`. These methods are indirect and a thread will asynchronously start or stop running on its own. Contrast this to coroutine methods which directly and immediately invoke execution or leave execution of a coroutine. Consider these examples: |
| + | |||
| + | ```lua | ||
| + | local thread = require("thread") | ||
| + | local t -- this example needs an upvalue to t | ||
| + | t = thread.create(function() | ||
| + | print("start") | ||
| + | thread.current():suspend() | ||
| + | print("after suspend") | ||
| + | os.sleep() | ||
| + | print("after sleep") | ||
| + | end) | ||
| + | ``` | ||
| + | |||
| + | Output: | ||
| + | ``` | ||
| + | start | ||
| + | ``` | ||
| ```lua | ```lua | ||
| Line 145: | Line 169: | ||
| t = thread.create(function() | t = thread.create(function() | ||
| print("start") | print("start") | ||
| - | t:suspend() | + | thread.current():suspend() |
| print("after suspend") | print("after suspend") | ||
| os.sleep() | os.sleep() | ||
| print("after sleep") | print("after sleep") | ||
| end) | end) | ||
| + | print("outside thread create") | ||
| + | t:resume() | ||
| + | print("after resume") | ||
| ``` | ``` | ||
| Line 155: | Line 182: | ||
| ``` | ``` | ||
| start | start | ||
| + | outside thread create | ||
| + | after suspend | ||
| + | after resume | ||
| + | after sleep | ||
| ``` | ``` | ||