9abb350 · urbit.org · git.iko.soy

content/docs/userspace/threads/basics/bind.md+1−1

compare with master

unifiedsplit

@@ -77,7 +77,7 @@ Here's a simple thread with a couple of `strandio` functions:

77(pure:m !>([s t]))

78```

79

80−Save it as `/ted/mythread.hoon`, `|commit` it and run it with `-mythread`. You should see something like:

80+Save it as `/ted/mythread.hoon` of `%base`, `|commit` it and run it with `-mythread`. You should see something like:

81

82```

83> -mythread

content/docs/userspace/threads/basics/fundamentals.md+16−17

@@ -15,23 +15,22 @@ Threads are managed by the gall agent called `spider`.

15

16## Thread location

17

18−Threads live in the `ted` directory of your desk:

18+Threads live in the `ted` directory of each desk. For example, in a desk named `%sandbox`:

19

20```

21−%

21+%sandbox

22├──app

23├──gen

24├──lib

25├──mar

26├──sur

27−├──sys

28└──ted <-

27└──ted <-

29 ├──foo

28 ├──foo

30 │ └──bar.hoon

29 │ └──bar.hoon

31 └──baz.hoon

30 └──baz.hoon

32```

31```

33

32

34−From the dojo, `ted/baz.hoon` can be run with `-baz`, and `ted/foo/bar.hoon` with `-foo-bar`.

33+From the dojo, `ted/baz.hoon` can be run with `-sandbox!baz`, and `ted/foo/bar.hoon` with `-sandbox!foo-bar`. Threads in the `%base` desk can just be run like `-foo`, but all others must have the format `-desk!thread`.

35

34

36**NOTE:** When the dojo sees the `-` prefix it automatically handles creating a thread ID, composing the argument, poking the `spider` gall agent and subscribing for the result. Running a thread from another context (eg. a gall agent) requires doing these things explicitly and is outside the scope of this particular tutorial.

35**NOTE:** When the dojo sees the `-` prefix it automatically handles creating a thread ID, composing the argument, poking the `spider` gall agent and subscribing for the result. Running a thread from another context (eg. a gall agent) requires doing these things explicitly and is outside the scope of this particular tutorial.

37

36

@@ -57,7 +56,7 @@ That is, a gate which takes a `vase` and returns the `form` of a `strand` that p

57

56

58![thread diagram](https://storage.googleapis.com/media.urbit.org/site/thread-diagram.png "diagram of a thread")

57![thread diagram](https://storage.googleapis.com/media.urbit.org/site/thread-diagram.png "diagram of a thread")

59

58

60−This is because threads typically do a bunch of I/O so it can't just immediately produce a result and end. Instead the strand will get some input, produce output, get some new input, produce new output, and so forth, until they eventually produce a `%done` with the actual final result.

59+This is because threads typically do a bunch of I/O so it can't just immediately produce a result and end. Instead the strand will get some input, produce output, get some new input, produce new output, and so forth, until they eventually produce a `%done` with the actual final result.

61

60

62## Strands

61## Strands

63

62

@@ -66,9 +65,10 @@ Strands are the building blocks of threads. A thread will typically compose mult

66A strand is a function of `strand-input:strand -> output:strand` and is defined in `/lib/strand/hoon`. You can see the details of `strand-input` [here](https://github.com/urbit/urbit/blob/master/pkg/arvo/lib/strand.hoon#L2-L21) and `output:strand` [here](https://github.com/urbit/urbit/blob/master/pkg/arvo/lib/strand.hoon#L23-L48). At this stage you don't need to know the nitty-gritty but it's helpful to have a quick look through. We'll discuss these things in more detail later.

65A strand is a function of `strand-input:strand -> output:strand` and is defined in `/lib/strand/hoon`. You can see the details of `strand-input` [here](https://github.com/urbit/urbit/blob/master/pkg/arvo/lib/strand.hoon#L2-L21) and `output:strand` [here](https://github.com/urbit/urbit/blob/master/pkg/arvo/lib/strand.hoon#L23-L48). At this stage you don't need to know the nitty-gritty but it's helpful to have a quick look through. We'll discuss these things in more detail later.

67

66

68A strand is a core that has three important arms:

67A strand is a core that has three important arms:

68+

69- `form` - the mold of the strand

70- `pure` - produces a strand that does nothing except return a value

71−- `bind` - monadic bind, like `then` in javascript promises

71+- `bind` - monadic bind, like `then` in javascript promises

72

73We'll discuss each of these arms later.

74

@@ -81,7 +81,7 @@ Strands are conventionally given the face `m` like:

81...

82```

83

84−**NOTE:** a comma prefix as in `,vase` is the irregular form of `^:` which is a gate that returns the sample value if it's of the correct type, but crashes otherwise.

84+**NOTE:** a comma prefix as in `,vase` is the irregular form of `^:` which is a gate that returns the sample value if it's of the correct type, but crashes otherwise.

85

86## Form and Pure

87

@@ -104,12 +104,12 @@ We'll cover `bind` later.

104## A trivial thread

105

106```hoon

107−/- spider

107+/- spider

108−=, strand=strand:spider

108+=, strand=strand:spider

109−^- thread:spider

109+^- thread:spider

110−|= arg=vase

110+|= arg=vase

111−=/ m (strand ,vase)

111+=/ m (strand ,vase)

112−^- form:m

112+^- form:m

113(pure:m arg)

114```

115

@@ -117,7 +117,6 @@ The above code is a simple thread that just returns its argument, and it's a goo

117

118Save the above code as a file in `ted/mythread.hoon` and `|commit` it. Run it with `-mythread 'foo'`, you should see the following:

119

120−

121```

120```

122> -mythread 'foo'

121> -mythread 'foo'

123[~ 'foo']

122[~ 'foo']

@@ -130,8 +129,8 @@ Save the above code as a file in `ted/mythread.hoon` and `|commit` it. Run it wi

130We'll go through it line-by line.

129We'll go through it line-by line.

131

130

132```hoon

131```hoon

133−/- spider

132+/- spider

134−=, strand=strand:spider

133+=, strand=strand:spider

135```

134```

136

135

137First we import `/sur/spider/hoon` which includes `/lib/strand/hoon` and give give the latter the face `strand` for convenience.

136First we import `/sur/spider/hoon` which includes `/lib/strand/hoon` and give give the latter the face `strand` for convenience.

@@ -155,7 +154,7 @@ We create a gate that takes a vase, the first part of the previously mentioned t

155Inside the gate we create our `strand` specialised to produce a `vase` and give it the canonical face `m`.

154Inside the gate we create our `strand` specialised to produce a `vase` and give it the canonical face `m`.

156

155

157```hoon

156```hoon

158−^- form:m

157+^- form:m

159```

158```

160

159

161We cast the output to `form` - the mold of the strand we created.

160We cast the output to `form` - the mold of the strand we created.

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

@@ -34,7 +34,7 @@ Here's a simple example of a thread that starts another thread:

34(pure:m !>(~))

35```

36

37−Save `parent.hoon` and `child.hoon` in `/ted`, `|commit %home` and run `-parent`. You should see something like:

37+Save `parent.hoon` and `child.hoon` in `/ted` of the `%base` desk, `|commit %base` and run `-parent`. You should see something like:

38

39```

40foo

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

74;< ~ bind:m %- poke-our

75 :* %spider

76 %spider-start

77− !>([`tid.bowl `tid %child !>(~)])

77+ !>([`tid.bowl `tid byk.bowl %child !>(~)])

78 ==

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

80;< ~ bind:m (take-kick /awaiting/[tid])

@@ -130,14 +130,15 @@ We pre-emptively subscribe for the result. Spider sends the result at `/thread-r

130;< ~ bind:m %- poke-our

131 :* %spider

132 %spider-start

133− !>([`tid.bowl `tid %child !>(~)])

133+ !>([`tid.bowl byk.bowl `tid %child !>(~)])

134 ==

135```

136

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

137+Spider takes a poke with a mark %spider-start and a vase containing `[parent=(unit tid) use=(unit tid) =beak 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.

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

141+- `beak` is a `[p=ship q=desk r=case]` triple which specifies the desk and revision containing the thread we want to run. In this case we just use `byk.bowl`.

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

142- `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

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

143

144

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

180;< ~ bind:m %- poke-our

181;< ~ bind:m %- poke-our

181 :* %spider

182 :* %spider

182 %spider-start

183 %spider-start

183− !>([`tid.bowl `tid %child !>(~)])

184+ !>([`tid.bowl byk.bowl `tid %child !>(~)])

184 ==

185 ==

185;< ~ bind:m (sleep ~s5)

186;< ~ bind:m (sleep ~s5)

186%- (slog leaf+"Stopping child thread..." ~)

187%- (slog leaf+"Stopping child thread..." ~)

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

@@ -75,7 +75,7 @@ Here's a simple thread that will:

75(pure:m !>(~))

76```

77

78−Save it as `/ted/latest-hash.hoon`, `|commit %home` and run it with `-latest-hash`. You should see something like:

78+Save it as `/ted/latest-hash.hoon` of the `%base` desk, `|commit %base` and run it with `-latest-hash`. You should see something like:

79

80```

81> -latest-hash

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

@@ -68,7 +68,7 @@ Here's an example of a thread that subscribes to `graph-store` for updates and n

68(pure:m !>(~))

69```

70

71−Save it in `/ted`, `|commit %home`, and run it with `-chat-watch`. Now try typing some messages in the chat and you should see them printed like:

71+Save it in `/ted`, `|commit %base`, and run it with `-chat-watch`. Now try typing some messages in the chat and you should see them printed like:

72

73```

74~zod/test-8488: [~zod] x

@@ -103,7 +103,7 @@ Once this is done, main-loop will just call the same function again which will a

103

104To try the same input against multiple function you must use another `strandio` function `handle`. Handle converts a `%skip` into a `[fail %ignore ~]`. When `main-loop` sees a `[fail %ignore ~]` it tries the next function in its list with the same input.

105

106−Here are two files: `tester.hoon` and `tested.hoon`. Save them both to `/ted`, `|commit %home` and run `-tester`. You should see:

106+Here are two files: `tester.hoon` and `tested.hoon`. Save them both to `/ted` in the `%base` desk, `|commit %base` and run `-tester`. You should see:

107

108```

109> -tester

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

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

47(pure:m !>(~))

48```

49

50−Save it in `/ted`, `|commit`, and run it like:

50+Save it in `/ted` of the `%base` desk, `|commit %base`, and run it like:

51

52```

53-post-msg [~zod %foo-9955] 'some message'

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

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

45

46**Note:** Pretty useless on a fake ship.

47

48−Save as `ted/get-ip.hoon`, `|commit %home`, and run it with `-get-ip ~bitbet-bolbel`. You should see something like:

48+Save as `ted/get-ip.hoon` in the `%base` desk, `|commit %base`, and run it with `-get-ip ~bitbet-bolbel`. You should see something like:

49

50```

5134.83.113.220:60659

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

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

42(pure:m !>(~))

43```

44

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

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

46

47### Analysis

48

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

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

29 (pair term term)

30 =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

31 =/ ta-now `@ta`(scot %da now.bowl)

32− =/ start-args [~ `tid p.q.vase !>(q.q.vase)]

32+ =/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

33 :_ this

34 :~

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

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

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

29 (pair term term)

30 =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

31 =/ ta-now `@ta`(scot %da now.bowl)

32− =/ start-args [~ `tid p.q.vase !>(q.q.vase)]

32+ =/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

33 :_ this

34 :~

35 [%pass /thread/[ta-now] %agent [our.bowl %spider] %poke %spider-start !>(start-args)]

@@ -76,7 +76,7 @@ And here's a minimal thread to test it with:

76==

77```

78

79−Save them as `/app/thread-starter.hoon` and `/ted/test-thread.hoon` respectively, `|commit %home`, and start the app with `|start %thread-starter`.

79+Save them as `/app/thread-starter.hoon` and `/ted/test-thread.hoon` respectively in the `%base` desk, `|commit %base`, and start the app with `|rein %base [& %thread-starter]`.

80

81Now you can poke it with a pair of thread name and argument like:

82

@@ -116,7 +116,7 @@ We can ignore the input logic, here's the important part:

116```hoon

117=/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

118=/ ta-now `@ta`(scot %da now.bowl)

119−=/ start-args [~ `tid p.q.vase !>(q.q.vase)]

119+=/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

120:_ this

121:~

122 [%pass /thread/[ta-now] %agent [our.bowl %spider] %poke %spider-start !>(start-args)]

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

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

29 (pair term term)

30 =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

31 =/ ta-now `@ta`(scot %da now.bowl)

32− =/ start-args [~ `tid p.q.vase !>(q.q.vase)]

32+ =/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

33 :_ this

34 :~

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

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

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

31 (pair term term)

32 =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

33 =/ ta-now `@ta`(scot %da now.bowl)

34− =/ start-args [~ `tid p.q.vase !>(q.q.vase)]

34+ =/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

35 :_ this

36 :~

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

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

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

29 (pair term term)

30 =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl)))

31 =/ ta-now `@ta`(scot %da now.bowl)

32− =/ start-args [~ `tid p.q.vase !>(q.q.vase)]

32+ =/ start-args [~ `tid byk.bowl p.q.vase !>(q.q.vase)]

33 :_ this

34 :~

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

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

@@ -9,10 +9,10 @@ Spider has an Eyre binding which allows threads to be run externally via [authen

9Spider is bound to the `/spider` URL path, and expects the requested URL to look like:

10

11```

12−http{s}://{host}/spider/{inputMark}/{threadName}/{outputMark}

12+http{s}://{host}/spider/{desk}/{inputMark}/{threadName}/{outputMark}

13```

14

15−The `inputMark` is the `mark` the thread takes. The `threadName` is the name of the thread, e.g. `foo` for `/ted/foo/hoon`. The `outputMark` is the `mark` the thread produces. You may also include a file extension though it doesn't have an effect.

15+The `desk` is the desk in which the thread resides. The `inputMark` is the `mark` the thread takes. The `threadName` is the name of the thread, e.g. `foo` for `/ted/foo/hoon`. The `outputMark` is the `mark` the thread produces. You may also include a file extension though it doesn't have an effect.

16

17When Spider receives an HTTP request, the following steps happen:

18

@@ -30,7 +30,7 @@ Thus, it's important to understand that the original HTTP request and final HTTP

30

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

32

33−Here's an extremely simple thread that takes a `vase` of `(unit json)` and just returns the `json` in a new `vase`. You can save it in `/ted` and `|commit %home`:

33+Here's an extremely simple thread that takes a `vase` of `(unit json)` and just returns the `json` in a new `vase`. You can save it in `/ted` and `|commit %base`:

34

35`eyre-thread.hoon`

36

@@ -48,14 +48,14 @@ Here's an extremely simple thread that takes a `vase` of `(unit json)` and just

48

49First we must obtain a session cookie by [authenticating](/docs/arvo/eyre/examples#authenticating).

50

51−Now we can try and run our thread. Spider is bound to the `/spider` URL path, and expects the rest of the path to be `/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread`, and both its `{inputMark}` and `{outputMark}` are `json`, so our URL path will be `/spider/json/eyre-agent/json`. Our request will be an HTTP POST request and the body will be some `json`, in this case `[{"foo": "bar"}]`:

51+Now we can try and run our thread. Spider is bound to the `/spider` URL path, and expects the rest of the path to be `/{desk}/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread` and is in the `%base` `{desk}`. Both its `{inputMark}` and `{outputMark}` are `json`. Therefore, our URL path will be `/spider/base/json/eyre-agent/json`. Our request will be an HTTP POST request and the body will be some `json`, in this case `[{"foo": "bar"}]`:

52

53```

54curl -i --header "Content-Type: application/json" \

55 --cookie "urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6" \

56 --request POST \

57 --data '[{"foo": "bar"}]' \

58− http://localhost:8080/spider/json/eyre-thread/json

58+ http://localhost:8080/spider/base/json/eyre-thread/json

59```

60

61Spider will run the thread and the result will be returned through Eyre in the body of an HTTP response with a 200 status code:

content/docs/userspace/threads/reference.md+11−2

@@ -10,20 +10,29 @@ Poke `spider` with mark `%spider-start` and a vase containing `start-args`:

10

11```hoon

12+$ start-args

13− [parent=(unit tid) use=(unit tid) file=term =vase]

13+ [parent=(unit tid) use=(unit tid) =beak file=term =vase]

14```

15

16Where:

17

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` for the `beak`.

20- `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`.

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

21- `vase` - `vase` to be given to the thread when it's started. Can be whatever or just `!>(~)` if it doesn't need any args.

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.

22

31

23#### Example

32#### Example

24

33

25```hoon

34```hoon

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

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

27```

36```

28

37

29## Stop thread

38## Stop thread