20d475b · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Merge pull request #1092 from tinnus-napbus/fix-threads-docs

fix threads docs

commit20d475bda85253a72ba53ac4b3a707e56aedefcf authortinnus-napbus <77721746+tinnus-napbus@users.noreply.github.com> dateTue 31 Aug 2021, 11:18 (5 years ago) parentcc058b5 b998398

14 files changed+111−119

compare with master

unifiedsplit

content/docs/userspace/threads/basics/summary.md+3−3

@@ -42,16 +42,16 @@ Now here's a quick recap of the main points covered:

4242- are conventionally given the face `m`.

4343- are a core that has three main arms - `form`, `pure` and `bind`:

4444

45−#### form

45+### form

4646

4747- is the mold of the strand suitable for casting

4848- is the type returned by the other arms

4949

50−#### pure

50+### pure

5151

5252- simply returns the `form` of a `strand` that produces pure's argument without doing any IO

5353

54−#### bind

54+### bind

5555

5656- is used to chain strands together like javascript promises

5757- is used in conjunction with micgal (`;<`)

content/docs/userspace/threads/examples/child-thread.md+33−33

@@ -4,31 +4,31 @@ weight = 2

44template = "doc.html"

55+++

7−Here's a simple example of a thread that starts another thread:

7+Here's a simple example of a thread that starts another thread:

9−### parent.hoon

9+#### `parent.hoon`

1010

1111```hoon

1212/- spider

1313/+ *strandio

1414=, strand=strand:spider

15−^- thread:spider

16−|= arg=vase

17−=/ m (strand ,vase)

15+^- thread:spider

16+|= arg=vase

17+=/ m (strand ,vase)

1818^- form:m

1919;< tid=tid:spider bind:m (start-thread %child)

2020(pure:m !>(~))

2121```

2222

23−### child.hoon

23+#### `child.hoon`

2424

2525```hoon

2626/- spider

2727/+ *strandio

2828=, strand=strand:spider

29−^- thread:spider

30−|= arg=vase

31−=/ m (strand ,vase)

29+^- thread:spider

30+|= arg=vase

31+=/ m (strand ,vase)

3232^- form:m

3333%- (slog leaf+"foo" ~)

3434(pure:m !>(~))

@@ -48,7 +48,7 @@ foo

4848;< tid=tid:spider bind:m (start-thread %child)

4949```

5050

51−See here how we gave `start-thread` the name of the thread to run. It returns the `tid` of the thread, which we could then use to poke it or whatever.

51+See here how we gave `start-thread` the name of the thread to run. It returns the `tid` of the thread, which we could then use to poke it or whatever.

5252

5353`start-thread` handles creating the `tid` for the thread so is quite convenient.

5454

@@ -58,15 +58,15 @@ Note that threads we start this way will be a child of the thread that started t

5858

5959If we want to actually get the result of the thread we started, it's slightly more complicated:

6060

61−### parent.hoon

61+#### `parent.hoon`

6262

6363```hoon

6464/- spider

6565/+ *strandio

6666=, strand=strand:spider

67−^- thread:spider

68−|= arg=vase

69−=/ m (strand ,vase)

67+^- thread:spider

68+|= arg=vase

69+=/ m (strand ,vase)

7070^- form:m

7171;< =bowl:spider bind:m get-bowl

7272=/ tid `@ta`(cat 3 'strand_' (scot %uv (sham %child eny.bowl)))

@@ -84,7 +84,7 @@ If we want to actually get the result of the thread we started, it's slightly mo

8484==

8585```

8686

87−### child.hoon

87+#### `child.hoon`

8888

8989```hoon

9090/- spider

@@ -94,9 +94,9 @@ If we want to actually get the result of the thread we started, it's slightly mo

9494|%

9595++ url "https://www.whatsthelatestbasehash.com/"

9696--

97−^- thread:spider

98−|= arg=vase

99−=/ m (strand ,vase)

97+^- thread:spider

98+|= arg=vase

99+=/ m (strand ,vase)

100100^- form:m

101101;< =cord bind:m (fetch-cord url)

102102=/ hash-as-cord `@t`(end [3 (sub (met 3 cord) 1)] cord)

@@ -104,7 +104,7 @@ If we want to actually get the result of the thread we started, it's slightly mo

104104(pure:m !>(hash))

105105```

106106

107−`child.hoon` simply grabs the latest base hash from https://www.whatsthelatestbasehash.com/ and returns it.

107+`child.hoon` simply grabs the latest base hash from https://www.whatsthelatestbasehash.com/ and returns it.

108108

109109`parent.hoon` is a bit more complicated so we'll look at it line-by-line

110110

@@ -136,10 +136,10 @@ We pre-emptively subscribe for the result. Spider sends the result at `/thread-r

136136

137137Spider takes a poke with a mark %spider-start and a vase containing `[parent=(unit tid) use=(unit tid) file=term =vase]` to start a thread, where:

138138

139−* `parent` is an optional parent thread. In this case we say the parent is our tid. Specifying a parent means the child will be killed if the parent ends.

140−* `use` is the thread ID for the thread we're creating

141−* `file` is the filename of the thread we want to start

142−* `vase` is the vase it will be given as an argument when it's started

139+- `parent` is an optional parent thread. In this case we say the parent is our tid. Specifying a parent means the child will be killed if the parent ends.

140+- `use` is the thread ID for the thread we're creating

141+- `file` is the filename of the thread we want to start

142+- `vase` is the vase it will be given as an argument when it's started

143143

144144```hoon

145145;< =cage bind:m (take-fact /awaiting/[tid])

@@ -164,15 +164,15 @@ Finally we test whether the thread produced a `%thread-done` or a `%thread-fail`

164164

165165## Stop a thread

166166

167−### parent.hoon

167+#### `parent.hoon`

168168

169169```hoon

170170/- spider

171171/+ *strandio

172172=, strand=strand:spider

173−^- thread:spider

174−|= arg=vase

175−=/ m (strand ,vase)

173+^- thread:spider

174+|= arg=vase

175+=/ m (strand ,vase)

176176^- form:m

177177;< =bowl:spider bind:m get-bowl

178178=/ tid `@ta`(cat 3 'strand_' (scot %uv (sham %child eny.bowl)))

@@ -193,7 +193,7 @@ Finally we test whether the thread produced a `%thread-done` or a `%thread-fail`

193193(pure:m !>("Done"))

194194```

195195

196−### child.hoon

196+#### `child.hoon`

197197

198198```hoon

199199/- spider

@@ -213,8 +213,8 @@ Finally we test whether the thread produced a `%thread-done` or a `%thread-fail`

213213 ==

214214--

215215^- thread:spider

216−|= arg=vase

217−=/ m (strand ,vase)

216+|= arg=vase

217+=/ m (strand ,vase)

218218^- form:m

219219;< ~ bind:m looper

220220(pure:m !>(~))

@@ -232,6 +232,6 @@ Finally we test whether the thread produced a `%thread-done` or a `%thread-fail`

232232 ==

233233```

234234

235−* `%spider-stop` is the mark that tells spider to kill a thread.

236−* `tid` is the tid of the thread to kill

237−* `%.y` tells spider to suppress traceback in the result of the killed thread. If you give it `%.n` it will include the traceback.

235+- `%spider-stop` is the mark that tells spider to kill a thread.

236+- `tid` is the tid of the thread to kill

237+- `%.y` tells spider to suppress traceback in the result of the killed thread. If you give it `%.n` it will include the traceback.

content/docs/userspace/threads/examples/get-json.md+5−4

@@ -4,18 +4,19 @@ weight = 1

44template = "doc.html"

55+++

7−Grabbing JSON from some url is very easy.

7+Grabbing JSON from some url is very easy.

99`strandio` includes the `fetch-json` function which will handle the http request and response parsing and just return unformatted json data.

1010

11−Here's a simple thread that will:

11+Here's a simple thread that will:

12+

1213- grab JSON of the latest base-hash from https://www.whatsthelatestbasehash.com/latesthash.json

1314- grab JSON of a list of all base-hashes with version info from https://www.whatsthelatestbasehash.com/all.json

1415- format and cast them

1516- check `all.json` includes the latest base-hash

1617- print the details of the latest base-hash to the dojo

1718

18−### latest-hash.hoon

19+#### `latest-hash.hoon`

1920

2021```hoon

2122/- spider

@@ -86,7 +87,7 @@ Release: https://github.com/urbit/urbit/releases/tag/urbit-os-v2.39

8687~

8788```

8889

89−## Analysis

90+### Analysis

9091

9192`fetch-json` takes a url as a tape, so we've added a core with the urls like:

9293

content/docs/userspace/threads/examples/main-loop.md+8−8

@@ -18,7 +18,7 @@ This is useful if you want to (for example) take an arbitrary number of facts.

1818

1919Here's an example of a thread that subscribes to `graph-store` for updates and nicely prints the messages (an extremely basic chat reader):

2020

21−#### chat-watch.hoon

21+#### `chat-watch.hoon`

2222

2323```hoon

2424/- spider

@@ -111,15 +111,15 @@ baz

111111~

112112```

113113

114−#### tester.hoon

114+#### `tester.hoon`

115115

116116```hoon

117117/- spider

118118/+ *strandio

119119=, strand=strand:spider

120−^- thread:spider

121−|= arg=vase

122−=/ m (strand ,vase)

120+^- thread:spider

121+|= arg=vase

122+=/ m (strand ,vase)

123123^- form:m

124124;< tid=tid:spider bind:m (start-thread %tested)

125125;< our=ship bind:m get-our

@@ -129,7 +129,7 @@ baz

129129(pure:m !>(~))

130130```

131131

132−#### tested.hoon

132+#### `tested.hoon`

133133

134134```hoon

135135/- spider

@@ -163,9 +163,9 @@ baz

163163 (pure:m ~)

164164 ==

165165--

166−^- thread:spider

166+^- thread:spider

167167|= arg=vase

168−=/ m (strand ,vase)

168+=/ m (strand ,vase)

169169^- form:m

170170;< ~ bind:m looper

171171(pure:m !>(~))

content/docs/userspace/threads/examples/poke-agent.md+2−2

@@ -6,7 +6,7 @@ template = "doc.html"

77Here's a thread that lets you post a message to a chat in graph-store:

9−#### post-msg.hoon

9+#### `post-msg.hoon`

1010

1111```hoon

1212/- spider

@@ -55,6 +55,6 @@ Save it in `/ted`, `|commit`, and run it like:

5555

5656(obviously change the channel name to whatever you have)

5757

58−## Analysis

58+### Analysis

5959

6060Pretty simple, just use `on-poke` with an argument of `[ship term] cage` where `term` is the agent and `cage` is whatever the particular agent expects.

content/docs/userspace/threads/examples/scry.md+10−10

@@ -6,12 +6,12 @@ template = "doc.html"

77Here's an example of a thread that scries ames for the IP address & port of a ship and nicely prints it:

9−#### get-ip.hoon

9+#### `get-ip.hoon`

1010

1111```hoon

1212/- spider

1313/+ strandio

14−=, strand=strand:spider

14+=, strand=strand:spider

1515=, strand-fail=strand-fail:libstrand:spider

1616|%

1717++ process-lanes

@@ -30,9 +30,9 @@ Here's an example of a thread that scries ames for the IP address & port of a sh

3030 %- (slog leaf+"{ip}:{port}" ~)

3131 (pure:m ~)

3232--

33−^- thread:spider

33+^- thread:spider

3434|= arg=vase

35−=/ m (strand ,vase)

35+=/ m (strand ,vase)

3636^- form:m

3737=/ utarget !< (unit @p) arg

3838?~ utarget

@@ -51,20 +51,20 @@ Save as `ted/get-ip.hoon`, `|commit %home`, and run it with `-get-ip ~bitbet-bol

515134.83.113.220:60659

5252```

5353

54−## Analysis

54+### Analysis

5555

5656Here we use the `strandio` function `scry` which takes an argument of `[mold path]` where:

5757

5858- `mold` is the return type of the scry

5959- `path` is the scry path formatted like:

60− 1. vane letter and care

61− 2. desk if scrying arvo or agent if scrying a gall agent

62− 3. rest of path

63−

60+ 1. vane letter and care

61+ 2. desk if scrying arvo or agent if scrying a gall agent

62+ 3. rest of path

63+

6464In our case the mold is `(list lane:ames)` and the path is `/ax//peers/(scot %p target)/forward-lane` like:

6565

6666```hoon

6767;< lanes=(list lane:ames) bind:m (scry:strandio (list lane:ames) /ax//peers/(scot %p target)/forward-lane)

6868```

6969

70−After that we just process the result in `++ process-lanes` and print it.

70+After that we just process the result in `++ process-lanes` and print it.

content/docs/userspace/threads/examples/take-fact.md+2−2

@@ -6,7 +6,7 @@ template = "doc.html"

77Taking a fact from an agent, arvo or whatever is easy. First you subscribe using `watch:strandio` or `watch-our:strandio`, then you use `take-fact:strandio` to receive the fact. Here's an example that takes an update from `graph-store` and prints the message to the dojo:

9−#### print-msg.hoon

9+#### `print-msg.hoon`

1010

1111```hoon

1212/- spider

@@ -44,7 +44,7 @@ Taking a fact from an agent, arvo or whatever is easy. First you subscribe using

4444

4545Create a chat on your fake zod if you don't have one already, then save it in `/ted`, `|commit %home`, and run `-print-msg`. Next, type some message in your chat and you'll see it printed in the dojo.

4646

47−## Analysis

47+### Analysis

4848

4949First we call `watch-our` to subscribe:

5050

content/docs/userspace/threads/gall/poke-thread.md+8−9

@@ -6,7 +6,7 @@ template = "doc.html"

77Here's a modified agent that pokes our thread. I've replaced some off the previous stuff because it was getting a little unwieldly.

9−#### thread-starter.hoon

9+#### `thread-starter.hoon`

1010

1111```hoon

1212/+ default-agent, dbug

@@ -70,15 +70,15 @@ Here's a modified agent that pokes our thread. I've replaced some off the previo

7070

7171And here we've modified the thread to take the poke and return it as the result:

7272

73−#### test-thread.hoon

73+#### `test-thread.hoon`

7474

7575```hoon

76−/- spider

76+/- spider

7777/+ *strandio

78−=, strand=strand:spider

79−^- thread:spider

80−|= arg=vase

81−=/ m (strand ,vase)

78+=, strand=strand:spider

79+^- thread:spider

80+|= arg=vase

81+=/ m (strand ,vase)

8282^- form:m

8383;< vmsg=vase bind:m (take-poke %foo)

8484(pure:m vmsg)

@@ -86,13 +86,12 @@ And here we've modified the thread to take the poke and return it as the result:

8686

8787Save them, `|commit` and run it like `:thread-starter [%test-thread %blah]`. You should see:

8888

89−

9089```

9190Result: blah

9291> :thread-starter [%test-thread %blah]

9392```

9493

95−## Analysis

94+### Analysis

9695

9796In our agent we've added this card:

9897

content/docs/userspace/threads/gall/start-thread.md+9−9

@@ -6,7 +6,7 @@ template = "doc.html"

77Here's an example of a barebones gall agent that just starts a thread:

9−#### thread-starter.hoon

9+#### `thread-starter.hoon`

1010

1111```hoon

1212/+ default-agent, dbug

@@ -20,7 +20,7 @@ Here's an example of a barebones gall agent that just starts a thread:

2020++ on-init on-init:def

2121++ on-save on-save:def

2222++ on-load on-load:def

23−++ on-poke

23+++ on-poke

2424 |= [=mark =vase]

2525 ^- (quip card _this)

2626 ?+ mark (on-poke:def mark vase)

@@ -60,14 +60,14 @@ Here's an example of a barebones gall agent that just starts a thread:

6060

6161And here's a minimal thread to test it with:

6262

63−#### test-thread.hoon

63+#### `test-thread.hoon`

6464

6565```hoon

66−/- spider

67−=, strand=strand:spider

68−^- thread:spider

69−|= arg=vase

70−=/ m (strand ,vase)

66+/- spider

67+=, strand=strand:spider

68+^- thread:spider

69+|= arg=vase

70+=/ m (strand ,vase)

7171^- form:m

7272|= strand-input:strand

7373?+ q.arg [~ %fail %not-foo ~]

@@ -109,7 +109,7 @@ Thread failed to start

109109/sys/vane/gall/hoon:<[1.370 9].[1.370 37]>

110110```

111111

112−## Analysis

112+### Analysis

113113

114114We can ignore the input logic, here's the important part:

115115

content/docs/userspace/threads/gall/stop-thread.md+8−8

@@ -6,7 +6,7 @@ template = "doc.html"

77Here we've added one last card to `on-poke` to stop the thread and a little extra to `on-agent` to print things for demonstrative purposes.

9−#### thread-starter.hoon

9+#### `thread-starter.hoon`

1010

1111```hoon

1212/+ default-agent, dbug

@@ -91,15 +91,15 @@ Here we've added one last card to `on-poke` to stop the thread and a little extr

9191

9292We've also added a `sleep` to the thread to keep it running for demonstration.

9393

94−#### test-thread.hoon

94+#### `test-thread.hoon`

9595

9696```hoon

97−/- spider

97+/- spider

9898/+ *strandio

99−=, strand=strand:spider

100−^- thread:spider

101−|= arg=vase

102−=/ m (strand ,vase)

99+=, strand=strand:spider

100+^- thread:spider

101+|= arg=vase

102+=/ m (strand ,vase)

103103^- form:m

104104;< =path bind:m take-watch

105105;< ~ bind:m (send-raw-card [%give %fact ~[path] %update !>("message 1")])

@@ -141,7 +141,7 @@ Thread cancelled successfully

141141Thread failed: cancelled

142142```

143143

144−## Analysis

144+### Analysis

145145

146146The card we've added to our agent:

147147

content/docs/userspace/threads/gall/take-facts.md+8−8

@@ -8,7 +8,7 @@ Most of the time you'll just want the final result like how we did previously. S

99Here we've added another card to subscribe for any facts sent by the thread and some small changes to `on-agent`:

1010

11−#### thread-starter.hoon

11+#### `thread-starter.hoon`

1212

1313```hoon

1414/+ default-agent, dbug

@@ -80,15 +80,15 @@ Here we've added another card to subscribe for any facts sent by the thread and

8080

8181We've also made some changes to the thread:

8282

83−#### test-thread.hoon

83+#### `test-thread.hoon`

8484

8585```hoon

86−/- spider

86+/- spider

8787/+ *strandio

88−=, strand=strand:spider

89−^- thread:spider

90−|= arg=vase

91−=/ m (strand ,vase)

88+=, strand=strand:spider

89+^- thread:spider

90+|= arg=vase

91+=/ m (strand ,vase)

9292^- form:m

9393;< =path bind:m take-watch

9494;< ~ bind:m (send-raw-card [%give %fact ~[path] %update !>("message 1")])

@@ -127,7 +127,7 @@ message 4

127127Thread failed: not-foo

128128```

129129

130−## Analysis

130+### Analysis

131131

132132In our agent's `on-poke` arm we've added another card to subscribe to `/thread/[tid]/updates`:

133133

content/docs/userspace/threads/gall/take-result.md+9−9

@@ -6,7 +6,7 @@ template = "doc.html"

77Here we've added an extra card to subscribe for the result and a couple of lines in on-agent to test if it succeeded:

9−#### thread-starter.hoon

9+#### `thread-starter.hoon`

1010

1111```hoon

1212/+ default-agent, dbug

@@ -71,14 +71,14 @@ Here we've added an extra card to subscribe for the result and a couple of lines

7171--

7272```

7373

74−#### test-thread.hoon

74+#### `test-thread.hoon`

7575

7676```hoon

77−/- spider

78−=, strand=strand:spider

79−^- thread:spider

80−|= arg=vase

81−=/ m (strand ,vase)

77+/- spider

78+=, strand=strand:spider

79+^- thread:spider

80+|= arg=vase

81+=/ m (strand ,vase)

8282^- form:m

8383|= strand-input:strand

8484?+ q.arg [~ %fail %not-foo ~]

@@ -101,9 +101,9 @@ Thread started successfully

101101Thread failed: not-foo

102102```

103103

104−## Analysis

104+### Analysis

105105

106−In `on-poke` we've added an extra card *before* the `%spider-start` poke to subscribe for the result:

106+In `on-poke` we've added an extra card _before_ the `%spider-start` poke to subscribe for the result:

107107

108108```hoon

109109[%pass /thread/[ta-now] %agent [our.bowl %spider] %watch /thread-result/[tid]]

content/docs/userspace/threads/http-api.md+1−1

@@ -26,7 +26,7 @@ When Spider receives an HTTP request, the following steps happen:

2626

2727Thus, it's important to understand that the original HTTP request and final HTTP response must contain JSON data, and therefore the input & output `mark`s you specify must each have a `mark` file in `/mar` that includes a conversion method for `json -> inputMark` and `outputMark -> json` respectively.

2828

29−# Example

29+## Example

3030

3131Here we'll look at running Spider threads through Eyre.

3232

content/docs/userspace/threads/reference.md+5−13

@@ -4,15 +4,7 @@ weight = 50

44template = "doc.html"

55+++

7−## Spider

8−

9−- [Start a thread](#start-thread)

10−- [Stop a thread](#stop-thread)

11−- [Subscribe to thread result](#subscribe-to-thread-result)

12−- [Subscribe to thread](#subscribe-to-thread)

13−- [Poke a thread](#poke-thread)

14−

15−### Start thread

7+## Start thread

168

179Poke `spider` with mark `%spider-start` and a vase containing `start-args`:

1810

@@ -34,7 +26,7 @@ Where:

3426[%pass /some-path %agent [our.bowl %spider] %poke %spider-start !>([~ `tid %foo !>(~)])]

3527```

3628

37−### Stop thread

29+## Stop thread

3830

3931Poke `spider` with mark `%spider-stop` and a vase containing `[tid ?]`, where:

4032

@@ -47,7 +39,7 @@ Poke `spider` with mark `%spider-stop` and a vase containing `[tid ?]`, where:

4739[%pass /some-path %agent [our.bowl %spider] %poke %spider-stop !>([tid %.y)]

4840```

4941

50−### Subscribe to thread result

42+## Subscribe for result

5143

5244Spider will send the result on `/thread-result/[tid]` so you can subscribe there for the result. You should subscribe before starting the thread.

5345

@@ -62,7 +54,7 @@ The result will have a mark of either `%thread-fail` or `%thread-done`.

6254[%pass /some-path %agent [our.bowl %spider] %watch /thread-result/[tid]]

6355```

6456

65−### Subscribe to thread

57+## Subscribe to thread

6658

6759You 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.

6860

@@ -72,7 +64,7 @@ You can subscribe to a thread on `/thread/[tid]/path`. Note this is for facts se

7264[%pass /some-path %agent [our.bowl %spider] %watch /thread/[tid]/thread-path]

7365```

7466

75−### Poke Thread

67+## Poke thread

7668

7769To poke a thread you poke spider with a mark of `%spider-input` and a vase of `[tid cage]`.

7870