# Behn API Reference In this document we describe the public interface for Behn. Namely, we describe each task that Behn can be `+pass`ed, 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`](#wait) for setting a timer and [`%rest`](#rest) for cancelling a timer. ## `%born` ```hoon [%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` ```hoon [%rest p=@da] ``` Cancel a timer. Behn takes in a `@da` and cancels the timer at that time if one had been set through that `$wire`, 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](/urbit-os/kernel/behn/examples.md#rest) section of the Examples document. ## `%drip` ```hoon [%drip p=vase] ``` `%drip` allows one to delay a gift until a timer set for `now` fires. A Client `%slip`s Behn a `%drip` task wrapping a gift to be `%give`n to a Target. This launches a sequence of `$move`s 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 `%give`n 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 `%give`s updates to the app directly and the app crashes, this may cause Clay to crash as well. If instead Clay `%pass`es 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` ```hoon [%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: ```hoon [%heck syn=sign-arvo] ``` ## `%trim` ```hoon [%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` ```hoon [%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` ```hoon [%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: ```hoon [%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](/urbit-os/kernel/behn/examples.md#wait) section of the Examples document. ## `%wake` ```hoon [%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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.urbit.org/urbit-os/kernel/behn/tasks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.