mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-10-26 15:49:50 +03:00
Merge pull request #475 from urbit/i/436/update-khan
khan: update api ref
This commit is contained in:
commit
f90fcafbc7
@ -12,13 +12,15 @@ not yet proper libraries for other languages that can make use of it. Therefore,
|
||||
these documents will only touch on Khan's internal interface.
|
||||
|
||||
Khan's internal interface lets you run threads via Khan rather than having to
|
||||
poke [Spider](/reference/arvo/threads/reference) and subscribe for the result. This interface is simpler and more
|
||||
ergonomic than Spider's, so is usually preferable.
|
||||
poke [Spider](/reference/arvo/threads/reference) and subscribe for the result.
|
||||
This interface is simpler and more ergonomic than Spider's, so is usually
|
||||
preferable.
|
||||
|
||||
There are currently three `task`s to run a thread: `%fard`, `%fyrd`, and `%lard`.
|
||||
Only `%fard` is currently documented in
|
||||
the [API Reference](/reference/arvo/khan/tasks) section, and a practical example
|
||||
is given in the [Example](/reference/arvo/khan/example) section.
|
||||
There are two `task`s for running threads from userspace:
|
||||
[`%fard`](/reference/arvo/khan/tasks#fard) and
|
||||
[`%lard`](/reference/arvo/khan/tasks#lard). The former is for running a thread
|
||||
from file and the latter is for running an "in-line" thread, where you pass
|
||||
Khan the thread directly.
|
||||
|
||||
## Sections
|
||||
|
||||
|
@ -3,31 +3,101 @@ title = "API Reference"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
Khan's external interface is still experimental, so there's only one `task` that
|
||||
is currently useful:
|
||||
These are the `task`s Khan can be passed and the `gift`s it can give.
|
||||
|
||||
## `%fard`
|
||||
## Tasks
|
||||
|
||||
Here are the `task`s you can pass Khan. You'd either use
|
||||
[`%fard`](#fard) to run a thread from a file or [`%lard`](#lard) to run
|
||||
an in-line thread.
|
||||
|
||||
### `%fard`
|
||||
|
||||
Run a thread from within Arvo.
|
||||
|
||||
```hoon
|
||||
[%fard p=(fyrd cage)]
|
||||
```
|
||||
|
||||
Run a thread from within Arvo
|
||||
|
||||
`p` contains the thread location, name, and start arguments. See the
|
||||
[`fyrd`](/reference/arvo/khan/types#fyrd) data type reference entry for details.
|
||||
|
||||
#### Returns
|
||||
|
||||
When the thread finishes, either by succeeding or failing, Khan will return an
|
||||
`%arow` `gift`, which looks like :
|
||||
[`%arow`](#arow) gift.
|
||||
|
||||
---
|
||||
|
||||
### `%fyrd`
|
||||
|
||||
External thread.
|
||||
|
||||
```hoon
|
||||
[%fyrd p=(fyrd cast)]
|
||||
```
|
||||
|
||||
This is passed to Khan by the runtime when a thread is run externally.
|
||||
You would not use this from userspace.
|
||||
|
||||
---
|
||||
|
||||
### `%lard`
|
||||
|
||||
In-line thread.
|
||||
|
||||
```hoon
|
||||
[%lard =bear =shed]
|
||||
```
|
||||
|
||||
The [`bear`](/reference/arvo/khan/types#bear) is either a `desk` or
|
||||
`beak`. The [`shed`](/reference/arvo/khan/types#shed) is the thread
|
||||
itself. Since Spider doesn't need to read out the thread from Clay, the
|
||||
`bear` doesn't do much apart from be included in the thread name that
|
||||
Spider generates. Khan will have Spider run the given thread, and
|
||||
eventually give an [`%arow`](#arow) gift back with the result.
|
||||
|
||||
#### Returns
|
||||
|
||||
When the thread eventually finishes (or if it fails), Khan with give an
|
||||
[`%arow`](#arow) gift back with the result.
|
||||
|
||||
---
|
||||
|
||||
## Gifts
|
||||
|
||||
These are the two `gift`s Khan can give. In userspace, you'd only
|
||||
receive an [`%arow`](#arow).
|
||||
|
||||
### `%arow`
|
||||
|
||||
In-arvo result.
|
||||
|
||||
```hoon
|
||||
[%arow p=(avow cage)]
|
||||
```
|
||||
|
||||
`p` either contains the result in a `cage`, or an error and stack trace if it
|
||||
failed. See the [`avow`](/reference/arvo/khan/types#avow) data type reference
|
||||
entry for details.
|
||||
This gift contains the result of a finished thread if successful, or an
|
||||
error and stack trace if it failed. It's given for threads run from
|
||||
within Arvo. See the [`avow`](/reference/arvo/khan/types#avow) entry in
|
||||
the types reference for more details.
|
||||
|
||||
---
|
||||
|
||||
### `%avow`
|
||||
|
||||
External result.
|
||||
|
||||
```hoon
|
||||
[%avow p=(avow page)]
|
||||
```
|
||||
|
||||
This gift contains the result of running a thread externally. You would
|
||||
not receive this in userspace.
|
||||
|
||||
|
||||
A `page` is a pair of `mark` and `noun`. See the
|
||||
[`avow`](/reference/arvo/khan/types#avow) entry in the types reference
|
||||
for more details of that mold builder.
|
||||
|
||||
---
|
||||
|
Loading…
Reference in New Issue
Block a user