In this document we describe the public interface for Behn. Namely, we describe each task that Behn can be passed, and which gift(s) Behn can give in return.
Most of Behn's tasks are only used by the kernel or runtime. The two tasks you're likely to use from userspace are %wait for setting a timer and %rest for cancelling a timer.
%born
[%born ~]
Each time you start your urbit, the Arvo kernel calls the %born task for Behn. When called, Behn gets the current time from Unix and updates its list of timers accordingly.
You would not use this task from userspace.
Returns
Behn does not return any gift in response to a %born task.
%rest
[%rest p=@da]
Cancel a timer.
Behn takes in a @da and cancels the timer at that time if it exists, then adjusts the next wakeup call from Unix if necessary.
Returns
Behn does not return any gift in response to a %rest task.
Example
See the %rest section of the Examples document.
%drip
[%drip p=vase]
%drip allows one to delay a gift until a timer set for now fires.
A Client %slips Behn a %drip task wrapping a gift to be given to a Target. This launches a sequence of moves as written here:
Client -- %slip %drip --> Behn -- %pass %wait --> Behn -- %give %wake --> Behn -- %give %meta --> Target
Here the %meta move is a wrapper for the %gift inside of the initial %drip wrapper.
%drip only handles gifts, and can only schedule gifts for as soon as possible after the prescribed timer fires.
%drip takes in a %give move in a vase.
A %drip task is not likely to be used from userspace.
Returns
In response to a %drip task, Behn will %pass a %wait to itself, which then triggers a %wake gift to itself, which then causes Behn to %give a %meta gift containing the gift originally %given to Behn when %drip was first called. That makes Behn its own client for %drip.
Example
Say an app (the Target) is subscribed to updates from Clay (the Client). If Clay %gives updates to the app directly and the app crashes, this may cause Clay to crash as well. If instead Clay %passes Behn a %drip task wrapping the update gift, Behn will set a timer for now that, when fired, will cause the update gift to be given. If it causes a crash then it will have been in response to the %drip move, thereby isolating Clay from the crash. Thus %drip acts as a sort of buffer against cascading sequences of crashes.
%huck
[%huck syn=sign-arvo]
Immediately gives back a sign-arvo.
You would not use this task from userspace.
Returns
Behn returns the input sign-arvo as a %heck gift:
[%heck syn=sign-arvo]
%trim
[%trim p=@ud]
This task is sent by the interpreter in order to free up memory. Behn does not do anything with this task, since it is not a good idea to forget your timers.
You would not use this task from userspace.
Returns
Behn does not return any gift in response to a %trim task.
%vega
[%vega ~]
This task informs the vane that the kernel has been upgraded. Behn does not do anything in response to this.
You would not use this task from userspace.
Returns
Behn does not return any gift in response to a %vega task.
%wait
[%wait p=@da]
Set timer.
This task sets a timer to fire at the @da specified in p.
Returns
Behn returns a %wake gift in response to a %wait task, once the timer has fired. A %wake gift looks like:
[%wake error=(unit tang)]
The error unit will be ~ if successful, or contain a traceback in the tang if the timer failed for some reason.
Example
See the %wait section of the Examples document.
%wake
[%wake ~]
This task is sent by the kernel when the Unix timer tells the kernel that it is time for Behn to wake up. This is often caused by a %doze gift that Behn originally sent to the kernel that is then forwarded to Unix, which is where the real timekeeping occurs.
You would not use this task from userspace.
Returns
In response to receiving this task, Behn may %give a %doze gift containing the @da of the next timer to elapse. Behn may also %give a %wake gift to itself.