Lick API Reference
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 tasks are documented below. Some of them are only used by the kernel or Vere. The ones you'd use from userspace are %spin
, %shut
, and %spit
.
%born
%born
New Unix process.
[%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
gifts to Vere and %soak
gifts with a $mark
and $noun
of [%disconnect ~]
to agents.
%spin
%spin
Open an IPC port.
[%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
gift to Vere in response to a %spin
task.
Example
See the example agent.
%shut
%shut
Close an IPC port.
[%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
gift to Vere in response to a %shut
task.
Example
See the example agent.
%spit
%spit
Send a noun to the IPC port.
[%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
to the port's owner.
Returns
Lick forwards the contents of the task as a %soak
gift to Vere.
Example
See the example agent.
%trim
%trim
Trim state (no-op).
[%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
%vega
[%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
%soak
Receive data from outside.
[%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
gift.
Gifts
Below are the gifts that Lick can give. Only the %soak
gift would be given to an agent, the rest are only given to Vere.
%spin
%spin
Open an IPC port.
[%spin =name]
Lick gives this gift to Vere in order to register a socket with the $path
specified in $name
.
%shut
%shut
Close an IPC port.
[%shut =name]
Lick gives this gift to Vere in order to close and remove the socket with the $path
specified in $name
.
%spit
%spit
Spit a noun to the IPC port.
[%spit =name =mark =noun]
Lick converts a %spit
task to this gift and gives it to Vere.
%soak
%soak
Soak a noun from the IPC port.
[%soak =name =mark =noun]
Lick converts a %soak
task 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.
Last updated