mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
Revert "%lick documentation"
This commit is contained in:
Pyry Kovanen
GitHub
parent
95a8f6d69e
commit
55a2f85c0c
@ -46,10 +46,6 @@ Jael manages keys and Azimuth state.
|
||||
|
||||
Khan is our thread dispatcher.
|
||||
|
||||
## [Lick](/reference/arvo/lick/lick)
|
||||
|
||||
Lick is our interprocess communication (IPC) vane. Unix process can communicate to applications on Urbit through IPC.
|
||||
|
||||
## [Concepts](/reference/arvo/concepts/)
|
||||
|
||||
Explanations of design decisions that are pervasive throughout Arvo.
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
+++
|
||||
title = "Lick"
|
||||
weight = 96
|
||||
sort_by = "weight"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
## [Overview](/reference/arvo/lick/lick)
|
||||
|
||||
An overview of Lick, Urbit's timer vane.
|
||||
|
||||
## [API Reference](/reference/arvo/lick/tasks)
|
||||
|
||||
The `task`s Lick takes and the `gift`s it returns.
|
||||
|
||||
## [Scry Reference](/reference/arvo/lick/scry)
|
||||
|
||||
The scry endpoints of Lick.
|
||||
|
||||
## [Examples](/reference/arvo/lick/examples)
|
||||
|
||||
Practical examples of using Lick's `task`s.
|
||||
@ -1,131 +0,0 @@
|
||||
+++
|
||||
title = "Examples"
|
||||
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 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`
|
||||
|
||||
```hoon
|
||||
/+ default-agent, dbug
|
||||
!:
|
||||
|%
|
||||
+$ versioned-state
|
||||
$% state-0
|
||||
==
|
||||
+$ state-0
|
||||
$: [%0 name=@tas]
|
||||
==
|
||||
+$ card card:agent:gall
|
||||
--
|
||||
%- agent:dbug
|
||||
=| state-0
|
||||
=* state -
|
||||
^- agent:gall
|
||||
|_ =bowl:gall
|
||||
+* this .
|
||||
default ~(. (default-agent this %|) bowl)
|
||||
++ on-init
|
||||
^- (quip card _this)
|
||||
:_ this
|
||||
[%pass / %arvo %l %spin /rumors/uart]~
|
||||
++ on-save !>(state)
|
||||
++ on-load
|
||||
|= old=vase
|
||||
^- (quip card _this)
|
||||
`this(state !<(state-0 old))
|
||||
++ on-poke
|
||||
|= [=mark =vase]
|
||||
^- (quip card _this)
|
||||
?> ?=(%uart-action mark)
|
||||
=/ act !<(action vase)
|
||||
?- -.act
|
||||
%spin
|
||||
:_ this
|
||||
[%pass / %arvo %l %spin name.act]~
|
||||
::
|
||||
%shut
|
||||
:_ this
|
||||
[%pass /shut %arvo %l %shut name.act]~
|
||||
::
|
||||
%spit
|
||||
:_ this
|
||||
[%pass /spit %arvo %l %spit name.act mark.act data.act]~
|
||||
==
|
||||
::
|
||||
++ on-peek
|
||||
|= =path
|
||||
^- (unit (unit cage))
|
||||
~& >> path
|
||||
=/ dev `@tas`(snag 2 path)
|
||||
?+ path (on-peek:default path)
|
||||
[%s %agents *] ``noun+!>(dev)
|
||||
==
|
||||
++ on-arvo
|
||||
|= [=wire =sign-arvo]
|
||||
^- (quip card _this)
|
||||
=/ cad +.sign-arvo
|
||||
~& > ['wire' wire]
|
||||
~& > ['sign-arvo' sign-arvo]
|
||||
?+ sign-arvo (on-arvo:default wire sign-arvo)
|
||||
[%lick %soak *]
|
||||
?+ mark.sign-arvo [~ this]
|
||||
::
|
||||
%connect
|
||||
:_ this
|
||||
:~ [%pass /subscribe %agent [our.bowl %rumors] %watch /rumors]
|
||||
==
|
||||
::
|
||||
%disconnect
|
||||
:_ this
|
||||
:~ [%pass /subscribe %agent [our.bowl %rumors] %leave ~]
|
||||
==
|
||||
::
|
||||
%error
|
||||
~& > ['Error: ' ;;(@tas noun.sign-arvo)]
|
||||
`this
|
||||
==
|
||||
==
|
||||
++ on-watch on-watch:default
|
||||
++ on-leave on-leave:default
|
||||
++ on-agent
|
||||
|= [=wire =sign:agent:gall]
|
||||
^- (quip card _this)
|
||||
?+ wire (on-agent:default wire sign)
|
||||
[%subscribe ~]
|
||||
?+ -.sign (on-agent:default wire sign)
|
||||
%watch-ack
|
||||
?~ p.sign
|
||||
((slog '%rumors-watcher: Subscribe succeeded!' ~) `this)
|
||||
((slog '%rumors-watcher: Subscribe failed!' ~) `this)
|
||||
::
|
||||
%kick
|
||||
%- (slog '%rumors-watcher: Got kick, resubscribing...' ~)
|
||||
:_ this
|
||||
:~ [%pass /subscribe %agent [our.bowl %rumors] %watch /rumors]
|
||||
==
|
||||
::
|
||||
%fact
|
||||
?+ p.cage.sign (on-agent:default wire sign)
|
||||
%rumor
|
||||
=/ rumor !<([when=@da what=@t] q.cage.sign)
|
||||
=/ print :(weld (scow %da when.rumor) ": " (trip what.rumor))
|
||||
~& (crip print)
|
||||
:_ this
|
||||
[%pass /spit %arvo %l %spit /rumors/uart %print (crip print)]~
|
||||
==
|
||||
==
|
||||
==
|
||||
::
|
||||
++ on-fail on-fail:default
|
||||
--
|
||||
```
|
||||
|
||||
@ -1,32 +0,0 @@
|
||||
+++
|
||||
title = "Overview"
|
||||
weight = 1
|
||||
+++
|
||||
|
||||
Urbit's inter-process communication (IPC) vane.
|
||||
|
||||
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
|
||||
|
||||
[API Reference](/reference/arvo/lick/tasks) - The `task`s Lick takes and the `gift`s it returns.
|
||||
|
||||
[Scry Reference](/reference/arvo/lick/scry) - The scry endpoints of Lick.
|
||||
|
||||
[Examples](/reference/arvo/lick/examples) - Practical examples of using Lick's `task`s.
|
||||
@ -1,47 +0,0 @@
|
||||
+++
|
||||
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`. The
|
||||
`desk` field in the `beak` must be empty (`%$`, e.g. `/=//=`).
|
||||
|
||||
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 name:lick) %la /=//=/ports)
|
||||
~[/hood/reciept/control /slick/control]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `%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])
|
||||
[~ [i=/gall/use/slick/0w3.IZWEn/~nec t=[i=/dill t=~[//term/1]]]]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `%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)
|
||||
%.y
|
||||
```
|
||||
|
||||
---
|
||||
@ -1,218 +0,0 @@
|
||||
+++
|
||||
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.
|
||||
|
||||
The only novel data type is `name`, which is just a `path` representing
|
||||
the name of a socket.
|
||||
|
||||
## 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 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 may give [`%spin`](#spin-1) gifts to Vere and [`%soak`](#soak-1)
|
||||
gifts with a `mark` and `noun` of `[%disconnect ~]` to agents.
|
||||
|
||||
---
|
||||
|
||||
### `%spin`
|
||||
|
||||
Open an IPC port.
|
||||
|
||||
```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 [`%spin`](#spin-1) gift to Vere in response to a `%spin`
|
||||
task.
|
||||
|
||||
#### Example
|
||||
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
---
|
||||
|
||||
### `%shut`
|
||||
|
||||
Close an IPC port.
|
||||
|
||||
```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 gives a [`%shut`](#shut-1) gift to Vere in response to a `%shut`
|
||||
task.
|
||||
|
||||
#### Example
|
||||
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
---
|
||||
|
||||
### `%spit`
|
||||
|
||||
Send a noun to the IPC port.
|
||||
|
||||
```hoon
|
||||
[%spit =name =mark =noun]
|
||||
```
|
||||
|
||||
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 [`%soak`](#soak-1) gift to
|
||||
Vere.
|
||||
|
||||
#### Example
|
||||
|
||||
See the [example agent](/reference/arvo/lick/examples).
|
||||
|
||||
---
|
||||
|
||||
### `%trim`
|
||||
|
||||
Trim state (no-op).
|
||||
|
||||
```hoon
|
||||
[%trim ~]
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### `%vega`
|
||||
|
||||
```hoon
|
||||
[%vega ~]
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### `%soak`
|
||||
|
||||
Receive data from outside.
|
||||
|
||||
```hoon
|
||||
[%soak =name =mark =noun]
|
||||
```
|
||||
|
||||
This `task` is sent to Lick by the runtime, you would not use it
|
||||
manually.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
@ -46,7 +46,6 @@ terminal driving, [Eyre](/reference/glossary/eyre) for the web server,
|
||||
[Iris](/reference/glossary/iris) for the HTTP client,
|
||||
[Jael](/reference/glossary/jael) for PKI management, and
|
||||
[Khan](/reference/glossary/khan) for external control and thread running.
|
||||
[Lick](/reference/glossary/lick) for external communication.
|
||||
|
||||
Vanes and other programs for Arvo are written in [Hoon](/reference/glossary/hoon).
|
||||
|
||||
|
||||
@ -1,24 +0,0 @@
|
||||
+++
|
||||
title = "Lick"
|
||||
|
||||
[extra]
|
||||
category = "arvo"
|
||||
|
||||
[glossaryEntry.lick]
|
||||
name = "lick"
|
||||
symbol = ""
|
||||
usage = "arvo"
|
||||
desc = "IPC vane Arvo. Allows for applications to communicate with earth."
|
||||
|
||||
+++
|
||||
**Lick** is the interprocess communication (IPC) [vane](/reference/glossary/vane) (kernel module).
|
||||
It allows for applications to open and close IPC ports to earth. For
|
||||
example, a [Gall](/reference/glossary/gall) agent can send a `%spin`
|
||||
card to open an IPC port and allow for an earth process to communicate
|
||||
with it through `%spit` and `%soak` cards.
|
||||
|
||||
Lick is located in `/base/sys/vane/lick.hoon` within [Arvo](/reference/glossary/arvo).
|
||||
|
||||
### Further Reading
|
||||
|
||||
- [The Lick reference](/reference/arvo/lick/lick): A technical guide to the Lick vane.
|
||||
@ -25,7 +25,6 @@ A **vane** is an [Arvo](/reference/glossary/arvo) kernel module that performs es
|
||||
- [Iris](/reference/glossary/iris), the server HTTP vane.
|
||||
- [Jael](/reference/glossary/jael), the security vane.
|
||||
- [Khan](/reference/glossary/khan), the control vane.
|
||||
- [Lick](/reference/glossary/Lick), the interprocess communication (IPC) vane.
|
||||
|
||||
### Further Reading
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user