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

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

compare with master

unifiedsplit

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

42- are conventionally given the face `m`.

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

44

45−#### form

45+### form

46

47- is the mold of the strand suitable for casting

48- is the type returned by the other arms

49

50−#### pure

50+### pure

51

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

53

54−#### bind

54+### bind

55

56- is used to chain strands together like javascript promises

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

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

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

4template = "doc.html"

5+++

6

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:

8

9−### parent.hoon

9+#### `parent.hoon`

10

11```hoon

12/- spider

13/+ *strandio

14=, strand=strand:spider

15−^- thread:spider

15+^- thread:spider

16−|= arg=vase

16+|= arg=vase

17−=/ m (strand ,vase)

17+=/ m (strand ,vase)

18^- form:m

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

20(pure:m !>(~))

21```

22

23−### child.hoon

23+#### `child.hoon`

24

25```hoon

26/- spider

27/+ *strandio

28=, strand=strand:spider

29−^- thread:spider

29+^- thread:spider

30−|= arg=vase

30+|= arg=vase

31−=/ m (strand ,vase)

31+=/ m (strand ,vase)

32^- form:m

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

34(pure:m !>(~))

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

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

49```

50

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.

52

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

54

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

58

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

60

61−### parent.hoon

61+#### `parent.hoon`

62

63```hoon

64/- spider

65/+ *strandio

66=, strand=strand:spider

67−^- thread:spider

67+^- thread:spider

68−|= arg=vase

68+|= arg=vase

69−=/ m (strand ,vase)

69+=/ m (strand ,vase)

70^- form:m

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

72=/ 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

84==

85```

86

87−### child.hoon

87+#### `child.hoon`

88

89```hoon

90/- spider

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

94|%

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

96--

97−^- thread:spider

97+^- thread:spider

98−|= arg=vase

98+|= arg=vase

99−=/ m (strand ,vase)

99+=/ m (strand ,vase)

100^- form:m

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

102=/ 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

104(pure:m !>(hash))

105```

106

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.

108

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

110

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

136

137Spider 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:

138

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.

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

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

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

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

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

143

144```hoon

145;< =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`

164

165## Stop a thread

166

167−### parent.hoon

167+#### `parent.hoon`

168

169```hoon

170/- spider

171/+ *strandio

172=, strand=strand:spider

173−^- thread:spider

173+^- thread:spider

174−|= arg=vase

174+|= arg=vase

175−=/ m (strand ,vase)

175+=/ m (strand ,vase)

176^- form:m

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

178=/ 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`

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

194```

195

196−### child.hoon

196+#### `child.hoon`

197

198```hoon

199/- spider

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

213 ==

214--

215^- thread:spider

216−|= arg=vase

216+|= arg=vase

217−=/ m (strand ,vase)

217+=/ m (strand ,vase)

218^- form:m

219;< ~ bind:m looper

220(pure:m !>(~))

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

232 ==

233```

234

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

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

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

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.

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

4template = "doc.html"

5+++

6

7−Grabbing JSON from some url is very easy.

7+Grabbing JSON from some url is very easy.

8

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

10

11−Here's a simple thread that will:

11+Here's a simple thread that will:

12+

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

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

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

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

14- format and cast them

15- format and cast them

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

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

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

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

17

18

18−### latest-hash.hoon

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

19

20

20```hoon

21```hoon

21/- spider

22/- spider

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

86~

87~

87```

88```

88

89

89−## Analysis

90+### Analysis

90

91

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

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

92

93

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.

18

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

20

21−#### chat-watch.hoon

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

22

23```hoon

24/- spider

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

111~

112```

113

114−#### tester.hoon

114+#### `tester.hoon`

115

116```hoon

117/- spider

118/+ *strandio

119=, strand=strand:spider

120−^- thread:spider

120+^- thread:spider

121−|= arg=vase

121+|= arg=vase

122−=/ m (strand ,vase)

122+=/ m (strand ,vase)

123^- form:m

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

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

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

129(pure:m !>(~))

130```

131

132−#### tested.hoon

132+#### `tested.hoon`

133

134```hoon

135/- spider

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

163 (pure:m ~)

164 ==

165--

166−^- thread:spider

166+^- thread:spider

167|= arg=vase

168−=/ m (strand ,vase)

168+=/ m (strand ,vase)

169^- form:m

170;< ~ bind:m looper

171(pure:m !>(~))

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

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

6

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

8

9−#### post-msg.hoon

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

10

11```hoon

12/- spider

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

55

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

57

58−## Analysis

58+### Analysis

59

60Pretty 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"

6

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

8

9−#### get-ip.hoon

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

10

11```hoon

12/- spider

13/+ strandio

14−=, strand=strand:spider

14+=, strand=strand:spider

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

16|%

17++ process-lanes

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

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

31 (pure:m ~)

32--

33−^- thread:spider

33+^- thread:spider

34|= arg=vase

35−=/ m (strand ,vase)

35+=/ m (strand ,vase)

36^- form:m

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

38?~ utarget

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

5134.83.113.220:60659

52```

53

54−## Analysis

54+### Analysis

55

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

57

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

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

60− 1. vane letter and care

60+ 1. vane letter and care

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

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

62− 3. rest of path

62+ 3. rest of path

63−

63+

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

65

66```hoon

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

68```

69

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"

6

7Taking 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:

8

9−#### print-msg.hoon

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

10

11```hoon

12/- spider

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

44

45Create 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.

46

47−## Analysis

47+### Analysis

48

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

50

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

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

6

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

8

9−#### thread-starter.hoon

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

10

11```hoon

12/+ default-agent, dbug

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

70

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

72

73−#### test-thread.hoon

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

74

75```hoon

76−/- spider

76+/- spider

77/+ *strandio

78−=, strand=strand:spider

78+=, strand=strand:spider

79−^- thread:spider

79+^- thread:spider

80−|= arg=vase

80+|= arg=vase

81−=/ m (strand ,vase)

81+=/ m (strand ,vase)

82^- form:m

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

84(pure:m vmsg)

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

86

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

88

89−

90```

89```

91Result: blah

90Result: blah

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

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

93```

92```

94

93

95−## Analysis

94+### Analysis

96

95

97In our agent we've added this card:

96In our agent we've added this card:

98

97

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

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

6

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

8

9−#### thread-starter.hoon

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

10

11```hoon

12/+ default-agent, dbug

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

20++ on-init on-init:def

21++ on-save on-save:def

22++ on-load on-load:def

23−++ on-poke

23+++ on-poke

24 |= [=mark =vase]

25 ^- (quip card _this)

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

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

60

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

62

63−#### test-thread.hoon

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

64

65```hoon

66−/- spider

66+/- spider

67−=, strand=strand:spider

67+=, strand=strand:spider

68−^- thread:spider

68+^- thread:spider

69−|= arg=vase

69+|= arg=vase

70−=/ m (strand ,vase)

70+=/ m (strand ,vase)

71^- form:m

72|= strand-input:strand

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

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

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

110```

111

112−## Analysis

112+### Analysis

113

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

115

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

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

6

7Here 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.

8

9−#### thread-starter.hoon

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

10

11```hoon

12/+ 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

91

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

93

94−#### test-thread.hoon

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

95

96```hoon

97−/- spider

97+/- spider

98/+ *strandio

99−=, strand=strand:spider

99+=, strand=strand:spider

100−^- thread:spider

100+^- thread:spider

101−|= arg=vase

101+|= arg=vase

102−=/ m (strand ,vase)

102+=/ m (strand ,vase)

103^- form:m

104;< =path bind:m take-watch

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

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

141Thread failed: cancelled

142```

143

144−## Analysis

144+### Analysis

145

146The card we've added to our agent:

147

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

8

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

10

11−#### thread-starter.hoon

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

12

13```hoon

14/+ default-agent, dbug

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

80

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

82

83−#### test-thread.hoon

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

84

85```hoon

86−/- spider

86+/- spider

87/+ *strandio

88−=, strand=strand:spider

88+=, strand=strand:spider

89−^- thread:spider

89+^- thread:spider

90−|= arg=vase

90+|= arg=vase

91−=/ m (strand ,vase)

91+=/ m (strand ,vase)

92^- form:m

93;< =path bind:m take-watch

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

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

127Thread failed: not-foo

128```

129

130−## Analysis

130+### Analysis

131

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

133

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

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

6

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

8

9−#### thread-starter.hoon

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

10

11```hoon

12/+ default-agent, dbug

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

71--

72```

73

74−#### test-thread.hoon

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

75

76```hoon

77−/- spider

77+/- spider

78−=, strand=strand:spider

78+=, strand=strand:spider

79−^- thread:spider

79+^- thread:spider

80−|= arg=vase

80+|= arg=vase

81−=/ m (strand ,vase)

81+=/ m (strand ,vase)

82^- form:m

83|= strand-input:strand

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

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

101Thread failed: not-foo

102```

103

104−## Analysis

104+### Analysis

105

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:

107

108```hoon

109[%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:

26

27Thus, 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.

28

29−# Example

29+## Example

30

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

32

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

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

4template = "doc.html"

5+++

6

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

16

8

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

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

18

10

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

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

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

35```

27```

36

28

37−### Stop thread

29+## Stop thread

38

30

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

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

40

32

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

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

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

48```

40```

49

41

50−### Subscribe to thread result

42+## Subscribe for result

51

43

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

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

53

45

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

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

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

63```

55```

64

56

65−### Subscribe to thread

57+## Subscribe to thread

66

58

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

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

68

60

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

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

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

73```

65```

74

66

75−### Poke Thread

67+## Poke thread

76

68

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

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

78

70