diff --git a/content/reference/arvo/_index.md b/content/reference/arvo/_index.md index 4a0ae41..3a9a4e5 100644 --- a/content/reference/arvo/_index.md +++ b/content/reference/arvo/_index.md @@ -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. diff --git a/content/reference/arvo/lick/_index.md b/content/reference/arvo/lick/_index.md new file mode 100644 index 0000000..f7ef471 --- /dev/null +++ b/content/reference/arvo/lick/_index.md @@ -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. diff --git a/content/reference/arvo/lick/examples.md b/content/reference/arvo/lick/examples.md new file mode 100644 index 0000000..d41f977 --- /dev/null +++ b/content/reference/arvo/lick/examples.md @@ -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 +-- +``` + diff --git a/content/reference/arvo/lick/lick.md b/content/reference/arvo/lick/lick.md new file mode 100644 index 0000000..2a90a4f --- /dev/null +++ b/content/reference/arvo/lick/lick.md @@ -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. diff --git a/content/reference/arvo/lick/scry.md b/content/reference/arvo/lick/scry.md new file mode 100644 index 0000000..4926bcc --- /dev/null +++ b/content/reference/arvo/lick/scry.md @@ -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 +``` + diff --git a/content/reference/arvo/lick/tasks.md b/content/reference/arvo/lick/tasks.md new file mode 100644 index 0000000..740dc28 --- /dev/null +++ b/content/reference/arvo/lick/tasks.md @@ -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. + diff --git a/content/reference/glossary/arvo.md b/content/reference/glossary/arvo.md index 44d7ec3..32a0717 100644 --- a/content/reference/glossary/arvo.md +++ b/content/reference/glossary/arvo.md @@ -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). diff --git a/content/reference/glossary/lick.md b/content/reference/glossary/lick.md new file mode 100644 index 0000000..f3da842 --- /dev/null +++ b/content/reference/glossary/lick.md @@ -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. diff --git a/content/reference/glossary/vane.md b/content/reference/glossary/vane.md index 76c63f5..af9b41d 100644 --- a/content/reference/glossary/vane.md +++ b/content/reference/glossary/vane.md @@ -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