Lick API Reference

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.

---