urbit/developers.urbit.org
1
1
Fork 0
mirror of https://github.com/urbit/developers.urbit.org.git synced 2024-08-16 17:20:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

lick changes

Browse Source
This commit is contained in:
Amadeo Bellotti 2023-07-06 09:48:38 -04:00
parent ba63e44a7e
commit 207cc8ba88
9 changed files with 335 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
content/reference/arvo/_index.md
View File

@ -46,6 +46,10 @@ 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.

22
content/reference/arvo/lick/_index.md Normal file
View File

@ -0,0 +1,22 @@
+++
title = "Lick"
weight = 20
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.

126
content/reference/arvo/lick/examples.md Normal file
View File

@ -0,0 +1,126 @@
+++
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 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.
`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
--
```

16
content/reference/arvo/lick/lick.md Normal file
View File

@ -0,0 +1,16 @@
+++
title = "Overview"
weight = 1
+++
Urbit's Interprocess Communication 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.
## 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.

35
content/reference/arvo/lick/scry.md Normal file
View File

@ -0,0 +1,35 @@
+++
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.
## `%a` - Read ports.
A scry with a `care` of `%a` will return a list of all registered IPC ports.
```
.^((list path) %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
```
.^((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.
```
.^(@ %lu /===/slick/control)
0
```

106
content/reference/arvo/lick/tasks.md Normal file
View File

@ -0,0 +1,106 @@
+++
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.
## `%born`
```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.
#### Returns
Lick returns a `%spin` `gift` to `vere` in response to a `%born` `task`.
## `%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.
#### Returns
Lick sends a `gift` of a `%spin` to `vere` in response to a `%spin` `task`.
#### Example
See the [%spin](/reference/arvo/lick/examples#spin) section of the Examples document.
## `%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.
#### Returns
Lick sends a `gift` of a `%shut` to `vere` in response to a `%shut` `task`.
#### Example
See the [%shut](/reference/arvo/lick/examples#shut) section of the Examples document.
## `%spit`
```hoon
[%spit name=path mark=mark noun=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.
#### Returns
Lick forwards the contents of the task as a gift to vere.
## `%trim`
```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.
#### 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`
```hoon
[%soak name=path mark=mark noun=noun]
```
Receives data from outside. 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.

1
content/reference/glossary/arvo.md
View File

@ -46,6 +46,7 @@ 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).

24
content/reference/glossary/lick.md Normal file
View File

@ -0,0 +1,24 @@
+++
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.

1
content/reference/glossary/vane.md
View File

@ -25,6 +25,7 @@ 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