mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 21:57:16 +03:00
khan: update api ref
This commit is contained in:
parent
1df4151666
commit
3a5580ae89
@ -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.
|
these documents will only touch on Khan's internal interface.
|
||||||
|
|
||||||
Khan's internal interface lets you run threads via Khan rather than having to
|
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
|
poke [Spider](/reference/arvo/threads/reference) and subscribe for the result.
|
||||||
ergonomic than Spider's, so is usually preferable.
|
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`.
|
There are two `task`s for running threads from userspace:
|
||||||
Only `%fard` is currently documented in
|
[`%fard`](/reference/arvo/khan/tasks#fard) and
|
||||||
the [API Reference](/reference/arvo/khan/tasks) section, and a practical example
|
[`%lard`](/reference/arvo/khan/tasks#lard). The former is for running a thread
|
||||||
is given in the [Example](/reference/arvo/khan/example) section.
|
from file and the latter is for running an "in-line" thread, where you pass
|
||||||
|
Khan the thread directly.
|
||||||
|
|
||||||
## Sections
|
## Sections
|
||||||
|
|
||||||
|
@ -3,31 +3,101 @@ title = "API Reference"
|
|||||||
weight = 2
|
weight = 2
|
||||||
+++
|
+++
|
||||||
|
|
||||||
Khan's external interface is still experimental, so there's only one `task` that
|
These are the `task`s Khan can be passed and the `gift`s it can give.
|
||||||
is currently useful:
|
|
||||||
|
|
||||||
## `%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
|
```hoon
|
||||||
[%fard p=(fyrd cage)]
|
[%fard p=(fyrd cage)]
|
||||||
```
|
```
|
||||||
|
|
||||||
Run a thread from within Arvo
|
|
||||||
|
|
||||||
`p` contains the thread location, name, and start arguments. See the
|
`p` contains the thread location, name, and start arguments. See the
|
||||||
[`fyrd`](/reference/arvo/khan/types#fyrd) data type reference entry for details.
|
[`fyrd`](/reference/arvo/khan/types#fyrd) data type reference entry for details.
|
||||||
|
|
||||||
#### Returns
|
#### Returns
|
||||||
|
|
||||||
When the thread finishes, either by succeeding or failing, Khan will return an
|
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
|
```hoon
|
||||||
[%arow p=(avow cage)]
|
[%arow p=(avow cage)]
|
||||||
```
|
```
|
||||||
|
|
||||||
`p` either contains the result in a `cage`, or an error and stack trace if it
|
This gift contains the result of a finished thread if successful, or an
|
||||||
failed. See the [`avow`](/reference/arvo/khan/types#avow) data type reference
|
error and stack trace if it failed. It's given for threads run from
|
||||||
entry for details.
|
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