Fundamentals

Introduction

A thread is like a transient gall agent. Unlike an agent, it can end and it can fail. The primary uses for threads are:

1. Complex IO, like making a bunch of external API calls where each call depends on the last. Doing this in an agent significantly increases its complexity and the risk of a mishandled intermediary state corrupting permanent state. If you spin the IO out into a thread, your agent only has to make one call to the thread and receive one response.

2. Testing - threads are very useful for writing complex tests for your agents.

Threads are managed by the Gall agent called %spider. You can poke %spider directly, or you can pass a task to the Khan thread runner vane and let it handle %spider for you.

Threads can be run from a file in the /ted directory, or an "inline thread" can be passed directly to Khan from within your agent.

Thread file location

Thread files live in the /ted directory of each desk. For example, in a desk named %sandbox:

%sandbox
├──app
├──gen
├──lib
├──mar
├──sur
└──ted <-
   ├──foo
   │  └──bar.hoon
   └──baz.hoon

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.

Libraries

There are two libraries that may be relevant:

• /sur/spider/hoon - this contains a few simple structures used by %spider. It's only relevant if you're running thread files by poking %spider directly. If you're running them by passing a task to Khan as is typical, it can be ignored.

• /lib/strandio/hoon - this contains a large collection of ready-made functions for use in threads. You'll likely use many of these when you write threads, so it's very useful.

Thread definition

A thread is defined as a $-(vase shed:khan). That is, a gate that takes a $vase and produces a $shed:khan. A $shed:khan is the +form of a strand that produces a $vase. This is a little confusing and we'll look at each part in detail later. For now, note that the thread doesn't just produce a result, it actually produces a strand that takes input and produces output from which a result can be extracted. It works something like this:

thread diagram

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.

Strands

Strands are the building blocks of threads. A thread will typically compose multiple strands.

A strand is a function of $strand-input:rand to $output:strand:rand, the latter of which is a +strand-output-raw:rand initialized with a particular mold:

$strand-input:rand

+$  strand-input
  $+  strand-input
  [=bowl in=(unit input)]

$strand-output-raw:rand

++  strand-output-raw
    |*  a=mold
    $+  strand-output-raw
    $~  [~ %done *a]
    $:  cards=(list card)
        $=  next
        $%  [%wait ~]
            [%skip ~]
            [%cont self=(strand-form-raw a)]
            [%fail err=error]
            [%done value=a]
        ==
    ==

At this stage you don't need to know the nitty-gritty details but it's helpful to have a quick look through the +rand arm in lull.hoon. We'll discuss these things in more detail later.

A strand is a core that has three important arms:

• +form - the mold of the strand

• +pure - produces a strand that does nothing except return a value

• +bind - monadic bind, like then in javascript promises

We'll discuss each of these arms later.

A strand must be specialised to produce a particular type like (strand:rand ,<type>). As previously mentioned, a thread produces a $vase so is specialised like (strand:rand ,vase). Within your thread you'll likely compose multiple strands which produce different types like (strand:rand ,@ud), (strand:rand ,[path cage]), etc, but the thread itself will always come back to a (strand:rand ,vase).

Strands are conventionally given the face m like:

=/  m  (strand:rand ,vase)
...

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

Form and Pure

+form

The +form arm is the mold of the strand, suitable for casting. The two other arms produce +forms so you'll cast everything to this like:

=/  m  (strand:rand ,@ud)
^-  form:m
...

+pure

Pure produces a strand that does nothing except return a value. So, (pure:(strand:rand ,@tas) %foo) is a strand that produces %foo without doing any IO.

We'll cover +bind later.

A trivial thread

|=  arg=vase
=/  m  (strand:rand ,vase)
^-  form:m
(pure:m arg)

The above code is a simple thread that just returns its argument, and it's a good boilerplate to start from.

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

> -mythread 'foo'
[~ 'foo']

NOTE: The dojo wraps arguments in a unit so that's why it's [~ 'foo'] rather than just 'foo'.

Analysis

We'll go through it line-by line.

|=  arg=vase

We create a gate that takes a vase, the first part of the previously mentioned thread definition.

=/  m  (strand:rand ,vase)

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

^-  form:m

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

(pure:m arg)

Finally we call +pure with the gate input arg as its argument. Since arg is a $vase it will return the +form of a +strand which produces a $vase. Thus we've created a thread in accordance with its type definition.

Inline Threads

While you can store threads as files in the /ted directory, you can also include threads directly in your Gall agent code and ask the Khan vane to run them.

While a stand-alone thread file is expected to be a $-(vase shed:khan), an inline thread is just a $shed:khan. That is, it doesn't take any initial argument argument. Instead, you can simply reference any data and functions available in its subject in the Gall agent.

Here's how a trivial inline thread that'll just return 123, a number pinned previously in the Gall agent, might look:

=/  dat=@ud  123
=/  =shed:khan
  =/  m  (strand:rand ,vase)
  ^-  form:m
  (pure:m !>(dat))

The $shed can then be passed to Kahn in card:

[%pass /thread %arvo %k %lard %mydesk shed]~

The result will come back into the +on-arvo arm of the Gall agent in an %arow gift.

Next we'll look at the third arm of a strand: +bind.