git.iko.soy/urbit.org
on 4bc06e1 help sign in
urbit.org/content/docs/userspace/threads/reference.md
87 lines 3.2 kB history raw
1+++
2title = "Reference"
3weight = 50
4template = "doc.html"
5+++
7## Start thread
9Poke `spider` with mark `%spider-start` and a vase containing `start-args`:
11```hoon
12+$ start-args
13 [parent=(unit tid) use=(unit tid) =beak file=term =vase]
14```
16Where:
18- `parent` - optional `tid` of parent thread if the thread is a child. If specified, the child thread will be killed with the parent thread ends.
19- `use` - `tid` (thread ID) to give the new thread. Can be generated with something like `(scot %ta (cat 3 'my-agent_' (scot %uv (sham eny))))`. However you do it, make sure it's unique.
20- `beak` - A `$beak` is a triple of `[p=ship q=desk r=case]`. `p` is always our ship, `q` is the desk which contains the thread we want to run. `r` is a `case`, which specifies a desk revision and is a tagged union of:
21 ```hoon
22 +$ case
23 $% [%da p=@da] :: date
24 [%tas p=@tas] :: label
25 [%ud p=@ud] :: number
26 ==
27 ```
28 You'll almost always just want the current revision, so you can specify the `case` as `da+now.bowl`. If the thread is on the same desk as the agent you can also just use `byk.bowl(r da+now)` for the `beak`.
29- `file` - name of the thread file in `/ted`. For example, if the thread you want to start is `/ted/foo/hoon` you'd specify `%foo`.
30- `vase` - `vase` to be given to the thread when it's started. Can be whatever or just `!>(~)` if it doesn't need any args.
32#### Example
34```hoon
35[%pass /some-path %agent [our.bowl %spider] %poke %spider-start !>([~ `tid byk.bowl %foo !>(~)])]
36```
38## Stop thread
40Poke `spider` with mark `%spider-stop` and a vase containing `[tid ?]`, where:
42- `tid` - the `tid` of the thread you want to stop
43- `?` - whether thread should end nicely. If `%.y` it'll end with mark `%thread-done` and the bunt value of a vase. If `%.n` it'll end with mark `%thread-fail` and a `[term tang]` where `term` is `%cancelled` and `tang` is `~`.
45#### Example
47```hoon
48[%pass /some-path %agent [our.bowl %spider] %poke %spider-stop !>([tid %.y)]
49```
51## Subscribe for result
53Spider will send the result on `/thread-result/[tid]` so you can subscribe there for the result. You should subscribe before starting the thread.
55The result will have a mark of either `%thread-fail` or `%thread-done`.
57- `%thread-fail` - has a vase containing a `[term tang]` where `term` is an error message and `tang` is a traceback.
58- `%thread-done` - has a vase of the result of the thread.
60#### Example
62```hoon
63[%pass /some-path %agent [our.bowl %spider] %watch /thread-result/[tid]]
64```
66## Subscribe to thread
68You can subscribe to a thread on `/thread/[tid]/path`. Note this is for facts sent off by the thread while it's running, not the final result. The path depends on the particular thread.
70#### Example
72```hoon
73[%pass /some-path %agent [our.bowl %spider] %watch /thread/[tid]/thread-path]
74```
76## Poke thread
78To poke a thread you poke spider with a mark of `%spider-input` and a vase of `[tid cage]`.
80- `tid` is the tid of the thread you want to poke
81- `cage` is whatever mark and vase you want to poke it with
83#### Example
85```hoon
86[%pass /some-path %agent [our.bowl %spider] %poke %spider-input !>([tid %foo !>('foooo')])]
87```