urbit/developers.urbit.org
1
1
Fork 0
mirror of https://github.com/urbit/developers.urbit.org.git synced 2024-09-11 13:55:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1 from tinnus-napbus/lick_vane

Browse Source 
lick: various docs tweaks
This commit is contained in:
mopfel-winrux 2023-07-20 09:40:58 -04:00 committed by GitHub
commit e8ebfed3a8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 198 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/reference/arvo/lick/_index.md
View File

@ -1,6 +1,6 @@
+++
title = "Lick"
weight = 20
weight = 96
sort_by = "weight"
insert_anchor_links = "right"
+++

11
content/reference/arvo/lick/examples.md
View File

@ -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
!:

20
content/reference/arvo/lick/lick.md
View File

@ -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

34
content/reference/arvo/lick/scry.md
View File

@ -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
```
---

184
content/reference/arvo/lick/tasks.md
View File

@ -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.
---