In this document we describe the public interface for Lick. Namely, we describe each task that Lick can be passed, 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
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
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
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
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 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 ~]
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.
[%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
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
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 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 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.