git.iko.soy/urbit.org
on ga/patch help sign in
urbit.org/content/docs/userspace/threads/basics/bind.md
97 lines 3.2 kB history raw
1+++
2title = "Bind"
3weight = 2
4template = "doc.html"
5+++
7Having looked at `form` and `pure`, we'll now look at the last `strand` arm `bind`. Bind is typically used in combination with micgal (`;<`).
9## Micgal
11Micgal takes four arguments like `spec hoon hoon hoon`. Given `;< a b c d`, it composes them like `((b ,a) c |=(a d))`. So, for example, these two expressions are equivalent:
13```hoon
14;< ~ bind:m (sleep:strandio ~s2)
15(pure:m !>(~))
16```
18and
20```hoon
21((bind:m ,~) (sleep:strandio ~s2) |=(~ (pure:m !>(~))))
22```
24Micgal exists simply for readability. The above isn't too bad, but consider this:
26```hoon
27;< a b c
28;< d e f
29;< g h i
31```
33...as opposed to this monstrosity: `((b ,a) c |=(a ((e ,d) f |=(d ((h ,g) i |=(g j))))))`
35## bind
37Bind by itself must be specialised like `(bind:m ,&lt;type>)` and it takes two arguments:
39- The first argument is a function that returns the `form` of a strand which produces `&lt;type>`.
40- The second argument is a gate whose sample is `&lt;type>` and which returns a `form`.
42Since you'll invariably use it in conjunction with micgal, the `&lt;type>` in `;< &lt;type> bind:m ...` will both specialise `bind` and specify the gate's sample.
44Bind calls the first function then, if it succeeded, calls the second gate with the result of the first as its sample. If the first function failed, it will instead just return an error message and not bother calling the next gate. So it's essentially "strand A then strand B".
46Since the second gate may itself contain another `;< &lt;type> bind:m ...`, you can see how this allows you to glue together an arbitrarily large pipeline, where subsequent gates depend on the previous ones.
48## strandio
50`/lib/strandio/hoon` contains a large collection of useful, ready-made functions for use in threads. For example:
52- `sleep` waits for the specified time.
53- `get-time` gets the current time.
54- `poke` pokes an agent.
55- `watch` subscribes to an agent.
56- `fetch-json` produces the JSON at a particular URL.
57- `retry` tries a strand repeatedly with exponential backoff until it succeeds.
58- `start-thread` starts another thread.
59- `send-raw-card` sends any card.
61...and many more.
63## Putting it together
65Here's a simple thread with a couple of `strandio` functions:
67```hoon
68/- spider
69/+ strandio
70=, strand=strand:spider
71^- thread:spider
72|= arg=vase
73=/ m (strand ,vase)
74^- form:m
75;< t=@da bind:m get-time:strandio
76;< s=ship bind:m get-our:strandio
77(pure:m !>([s t]))
78```
80Save it as `/ted/mythread.hoon`, `|commit` it and run it with `-mythread`. You should see something like:
82```
83> -mythread
84[~zod ~2021.3.8..14.52.15..bdfe]
85```
87## Analysis
89To use `strandio` functions we've imported the library with `/+ strandio`.
91`get-time` and `get-our` get the current time & ship from the bowl in `strand-input`. We'll discuss `strand-input` in more detail later.
93Note how we've specified the face and return type of each strand like `t=@da`, etc.
95You can see how `pure` has access to the results of previous strands in the pipeline. Note how we've wrapped `pure`'s argument in a `!>` because the thread must produce a `vase`.
97Next we'll look at `strand-input` in more detail.