mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
Merge pull request #1 from tinnus-napbus/lick_vane
lick: various docs tweaks
This commit is contained in:
commit
e8ebfed3a8
@ -1,6 +1,6 @@
|
||||
+++
|
||||
title = "Lick"
|
||||
weight = 20
|
||||
weight = 96
|
||||
sort_by = "weight"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
@ -5,10 +5,15 @@ weight = 4
|
||||
|
||||
## %receipt
|
||||
|
||||
Below is an example of an application that spins up a lick port on its init call. When it recieves a `%connected` soak is subscribes to %rumors. whenever a %rumor is recieved it will spit it out
|
||||
to the Lick port and which will forward it to a reciept printer. When the receipt printer disconnects the application will unsubscribe to %rumors and wait.
|
||||
Below is an example of an application that spins up a lick port on its
|
||||
init call. When it recieves a `%connected` soak it subscribes to
|
||||
`%rumors`. whenever a `%rumor` is recieved it will spit it out to the
|
||||
Lick port and which will forward it to a reciept printer. When the
|
||||
receipt printer disconnects the application will unsubscribe to
|
||||
`%rumors` and wait.
|
||||
|
||||
### `receipt.hoon`
|
||||
|
||||
`receipt.hoon`
|
||||
```hoon
|
||||
/+ default-agent, dbug
|
||||
!:
|
||||
|
@ -3,9 +3,25 @@ title = "Overview"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
Urbit's Interprocess Communication vane.
|
||||
Urbit's inter-process communication (IPC) vane.
|
||||
|
||||
Lick manages IPC ports and the communication between Urbit applications and POSIX applciations. Other vanes and applications ask Lick to open an IPC port, notify it when something is connected or disconnected, and transfer data between itself and the Unix application.
|
||||
Lick manages IPC ports, and the communication between Urbit applications and
|
||||
POSIX applications via these ports. Other vanes and applications ask Lick to
|
||||
open an IPC port, notify it when something is connected or disconnected, and
|
||||
transfer data between itself and the Unix application.
|
||||
|
||||
The IPC ports Lick creates are Unix domain sockets (`AF_UNIX` address family)
|
||||
of the `SOCK_STREAM` type.
|
||||
|
||||
Data sent to and from the socket is a [++jam](/reference/hoon/stdlib/2p#jam)med
|
||||
pair of `mark` and `noun`. The process on the host OS must therefore be able to
|
||||
[`++cue`](/reference/hoon/stdlib/2p#cue) the jam and (most likely) convert the
|
||||
noun into a native data structure. A couple of examples of libraries for this
|
||||
purpose are [`pynoun`](https://github.com/urbit/tools) and
|
||||
[`nockjs`](https://github.com/urbit/nockjs).
|
||||
|
||||
Lick has no novel data types in its API apart from `name`, which is just a
|
||||
`path` representing the name of a socket.
|
||||
|
||||
## Sections
|
||||
|
||||
|
@ -3,33 +3,45 @@ title = "Scry Reference"
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
Here are Lick's scry endpoints. There's only a few and they're mostly just useful for debugging. All of Lick's scries are specified by a `care`, which is a single character corresponding to a command.
|
||||
The only `beam` it will respond to is the local identify, current timestamp, and any additonal informaiton a `care` needs.
|
||||
Here are Lick's scry endpoints. There's only a few and they're mostly just
|
||||
useful for debugging. All of Lick's scries are specified by a `care`. The
|
||||
`desk` field in the `beak` must be empty (`%$`, e.g. `/=//=`).
|
||||
|
||||
## `%a` - Read ports.
|
||||
The only novel data type is a `name`, which is just a `path` representing the
|
||||
name of a socket.
|
||||
|
||||
## `%a` - Read ports
|
||||
|
||||
A scry with a `care` of `%a` will return a list of all registered IPC ports.
|
||||
|
||||
```
|
||||
.^((list path) %la /=//=/ports)
|
||||
.^((list name:lick) %la /=//=/ports)
|
||||
~[/hood/reciept/control /slick/control]
|
||||
```
|
||||
|
||||
## `%d` - Port Owner
|
||||
---
|
||||
|
||||
A scry with a `care` of `%d` will return the duct of the IPC Port Owner. The `beam` will have to in clude the port identifier
|
||||
## `%d` - Port owner
|
||||
|
||||
A scry with a `care` of `%d` and the socket `name` in the `spur` will return
|
||||
the `duct` of the IPC port owner in a `unit`, which is null if the socket
|
||||
doesn't exist.
|
||||
|
||||
```
|
||||
.^((unit duct) %ld /===/[port-name])
|
||||
.^((unit duct) %ld /=//=/[port-name])
|
||||
[~ [i=/gall/use/slick/0w3.IZWEn/~nec t=[i=/dill t=~[//term/1]]]]
|
||||
```
|
||||
|
||||
## `%u` - Port Existance
|
||||
---
|
||||
|
||||
A scry with a `care` of `%u` will return if Lick has a Port registered in its state.
|
||||
## `%u` - Port existance
|
||||
|
||||
A scry with a `care` of `%u` and the socket `name` in the `spur` will return a
|
||||
`?` which is `%.y` if the socket exists in Lick's state.
|
||||
|
||||
```
|
||||
.^(@ %lu /===/slick/control)
|
||||
0
|
||||
.^(? %lu /=//=/slick/control)
|
||||
%.y
|
||||
```
|
||||
|
||||
---
|
||||
|
@ -3,104 +3,216 @@ title = "API Reference"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
In this document we describe the public interface for Lick. Namely, we describe each `task` that Lick can be `pass`ed, and which `gift`(s) Lick can `give` in return.
|
||||
In this document we describe the public interface for Lick. Namely, we
|
||||
describe each `task` that Lick can be `pass`ed, and which `gift`(s) Lick
|
||||
can `give` in return.
|
||||
|
||||
The only novel data type is `name`, which is just a `path` representing
|
||||
the name of a socket.
|
||||
|
||||
## `%born`
|
||||
## Tasks
|
||||
|
||||
Lick's `task`s are documented below. Some of them are only used by the
|
||||
kernel or Vere. The ones you'd use from userspace are [`%spin`](#spin`),
|
||||
[`%shut`](#shut), and [`%spit`](#spit).
|
||||
|
||||
### `%born`
|
||||
|
||||
New Unix process.
|
||||
|
||||
```hoon
|
||||
[%born ~]
|
||||
```
|
||||
|
||||
Each time you start your urbit, the Arvo kernel calls the `%born` task for Lick. When called, Lick will send every IPC port in it state to `vere` and send a `%disconnect` `%soak` to each IPC port owner.
|
||||
Each time you start your urbit, the Arvo kernel passes a `%born` task to
|
||||
Lick. When called, Lick will send every IPC port in it state to Vere
|
||||
and send a `%disconnect` `%soak` to each IPC port owner.
|
||||
|
||||
This `task` would not be used from userspace.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick returns a `%spin` `gift` to `vere` in response to a `%born` `task`.
|
||||
Lick may give [`%spin`](#spin-1) gifts to Vere and [`%soak`](#soak-1)
|
||||
gifts with a `mark` and `noun` of `[%disconnect ~]` to agents.
|
||||
|
||||
## `%spin`
|
||||
---
|
||||
|
||||
### `%spin`
|
||||
|
||||
```hoon
|
||||
[%spin name=path]
|
||||
```
|
||||
Open an IPC port.
|
||||
|
||||
Lick takes in a `path` and saves the `duct` that sent it as the owner then forwards the call to `vere`. `vere` will open an IPC port on the host OS and wait for something to connect to it.
|
||||
```hoon
|
||||
[%spin =name]
|
||||
```
|
||||
|
||||
Lick takes in a `path` and saves the `duct` that sent it as the owner,
|
||||
then forwards the call to Vere. Vere will open a socket with the given
|
||||
`name` on the host OS.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick sends a `gift` of a `%spin` to `vere` in response to a `%spin` `task`.
|
||||
Lick sends a [`%spin`](#spin-1) gift to Vere in response to a `%spin`
|
||||
task.
|
||||
|
||||
#### Example
|
||||
|
||||
See the [%spin](/reference/arvo/lick/examples#spin) section of the Examples document.
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
## `%shut`
|
||||
---
|
||||
|
||||
### `%shut`
|
||||
|
||||
```hoon
|
||||
[%shut name=path]
|
||||
```
|
||||
Close an IPC port.
|
||||
|
||||
Lick takes a `path` and removes it from its state. It also forwards the `path` to `vere` which inturn disconnects the IPC port from anything connected to it and closes it.
|
||||
```hoon
|
||||
[%shut =name]
|
||||
```
|
||||
|
||||
Lick takes a socket `path` and removes it from its state. It also
|
||||
forwards the `path` to Vere which disconnects the socket from anything
|
||||
connected to it and closes it.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick sends a `gift` of a `%shut` to `vere` in response to a `%shut` `task`.
|
||||
Lick gives a [`%shut`](#shut-1) gift to Vere in response to a `%shut`
|
||||
task.
|
||||
|
||||
#### Example
|
||||
|
||||
See the [%shut](/reference/arvo/lick/examples#shut) section of the Examples document.
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
## `%spit`
|
||||
---
|
||||
|
||||
### `%spit`
|
||||
|
||||
Send a noun to the IPC port.
|
||||
|
||||
```hoon
|
||||
[%spit name=path mark=mark noun=noun]
|
||||
[%spit =name =mark =noun]
|
||||
```
|
||||
|
||||
Sends a `[mark noun]` cell to the IPC vane.
|
||||
|
||||
Lick will send a newt-jammed `[mark noun]` cell to the IPC port if something is connected to it. If nothing is connected to the port, Lick will send an `%error` `%soak` to the port's owner.
|
||||
Lick will send the jammed `[mark noun]` cell to the socket `name` if
|
||||
something is connected to it. If nothing is connected to the port, Lick
|
||||
will send an `%error` [`%soak`](#soak-1) to the port's owner.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick forwards the contents of the task as a gift to vere.
|
||||
Lick forwards the contents of the task as a [`%soak`](#soak-1) gift to
|
||||
Vere.
|
||||
|
||||
## `%trim`
|
||||
#### Example
|
||||
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
---
|
||||
|
||||
### `%trim`
|
||||
|
||||
Trim state (no-op).
|
||||
|
||||
```hoon
|
||||
[%trim ~]
|
||||
```
|
||||
|
||||
This `task` is sent by the interpreter in order to free up memory. Lick does not do anything with this `task`, since it is not a good idea to forget your IPC ports.
|
||||
|
||||
You would not use this `task` from userspace.
|
||||
This `task` is sent by Arvo in order to free up memory. Lick does not do
|
||||
anything with this `task`, since it is not a good idea to forget your
|
||||
IPC ports.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick does not return any `gift` in response to a `%trim` `task`.
|
||||
Lick does not return any `gift` in response to a `%trim` task.
|
||||
|
||||
## `%vega`
|
||||
---
|
||||
|
||||
### `%vega`
|
||||
|
||||
```hoon
|
||||
[%vega ~]
|
||||
```
|
||||
|
||||
This `task` informs the vane that the kernel has been upgraded. Lick does not do anything in response to this.
|
||||
This `task` informs the vane that the kernel has been upgraded. Lick
|
||||
does not do anything in response to this.
|
||||
|
||||
You would not use this `task` from userspace.
|
||||
|
||||
#### Returns
|
||||
|
||||
Lick does not return any `gift` in response to a `%vega` `task`.
|
||||
Lick does not return any `gift` in response to a `%vega` task.
|
||||
|
||||
## `%soak`
|
||||
---
|
||||
|
||||
### `%soak`
|
||||
|
||||
Receive data from outside.
|
||||
|
||||
```hoon
|
||||
[%soak name=path mark=mark noun=noun]
|
||||
[%soak =name =mark =noun]
|
||||
```
|
||||
|
||||
Receives data from outside. This `task` is sent to Lick by the runtime, you would not use it manually.
|
||||
This `task` is sent to Lick by the runtime, you would not use it
|
||||
manually.
|
||||
|
||||
The `name` is associated with the `duct` that registered it and the `%soak` is forwarded to it.
|
||||
The socket `name` is associated with the `duct` that registered it. The
|
||||
`%soak` is forwarded to it as a [`%soak`](#soak-1) gift.
|
||||
|
||||
---
|
||||
|
||||
## Gifts
|
||||
|
||||
Below are the `gift`s that Lick can give. Only the [`%soak`](#soak-1)
|
||||
gift would be given to an agent, the rest are only given to Vere.
|
||||
|
||||
### `%spin`
|
||||
|
||||
Open an IPC port.
|
||||
|
||||
```hoon
|
||||
[%spin =name]
|
||||
```
|
||||
|
||||
Lick gives this `gift` to Vere in order to register a socket with the
|
||||
`path` specified in `name`.
|
||||
|
||||
---
|
||||
|
||||
### `%shut`
|
||||
|
||||
Close an IPC port.
|
||||
|
||||
```hoon
|
||||
[%shut =name]
|
||||
```
|
||||
|
||||
Lick gives this `gift` to Vere in order to close and remove the socket
|
||||
with the `path` specified in `name`.
|
||||
|
||||
---
|
||||
|
||||
### `%spit`
|
||||
|
||||
Spit a noun to the IPC port.
|
||||
|
||||
```hoon
|
||||
[%spit =name =mark =noun]
|
||||
```
|
||||
|
||||
Lick converts a [`%spit` task](#spit) to this `gift` and gives it to
|
||||
Vere.
|
||||
|
||||
---
|
||||
|
||||
### `%soak`
|
||||
|
||||
Soak a noun from the IPC port.
|
||||
|
||||
```hoon
|
||||
[%soak =name =mark =noun]
|
||||
```
|
||||
|
||||
Lick converts a [`%soak` task](#soak) from Vere into this `gift` and
|
||||
gives it to the agent that registered the `name` socket, representing an
|
||||
incoming message. It will also give a `%soak` with a `mark` and `noun`
|
||||
of `[%disconnect ~]` if the socket is closed. This is the only Lick
|
||||
`gift` an agent would receive.
|
||||
|
||||
---
|
||||
|
Loading…
Reference in New Issue
Block a user