<commit_before>+++
title = "2.7 Gall"
weight = 35
template = "doc.html"
aliases = ["/docs/learn/hoon/hoon-tutorial/gall/"]
+++

Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.

For additional information on Gall, see the [Gall docs](@/docs/arvo/gall/_index.md).

## bowl and moves

The [core](/docs/glossary/core/) of a gall app is a [door](/docs/glossary/door/) which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.

Vanes in Arvo communicate by means of `moves`. When a move is produced by an [arm](/docs/glossary/arm/) in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.

A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding to an incoming `move` you can use the `bone` in that `move` to construct your response.

A `card` is the effect or event that is being requested. Each application should define the set of `cards` it can produce. Here is an excerpt from `clock.hoon` showing its `cards`

```hoon
+$  card
  $%  [%poke wire dock poke]
      [%http-response =http-event:http]
      [%connect wire binding:eyre term]
      [%diff %json json]
  ==
```

Each `card` is a pair of a tag and a [noun](/docs/glossary/noun/). The tag indicates what the event being triggered is and the [noun](/docs/glossary/noun/) is any data required for that event.

## Arms

Gall applications can have a number of arms that get called depending on the information they are sent.

### +on-agent

This arm is called once when the agent is started.  It has no input and
lets you perform any initial IO.

### +on-init

This arm is called when the app is initially started.

### +on-save

This arm is called immediately before the agent is upgraded.  It
packages the permament state of the agent in a `vase` for the next version
of the agent.  Unlike most handlers, this cannot produce effects.

### +on-load

This arm is called immediately after the agent is upgraded.  It receives<commit_msg>Re-fix the headers<commit_after>+++
title = "2.7 Gall"
weight = 35
template = "doc.html"
aliases = ["/docs/learn/hoon/hoon-tutorial/gall/"]
+++

Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.

For additional information on Gall, see the [Gall docs](@/docs/arvo/gall/_index.md).

## bowl and moves

The [core](/docs/glossary/core/) of a gall app is a [door](/docs/glossary/door/) which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.

Vanes in Arvo communicate by means of `moves`. When a move is produced by an [arm](/docs/glossary/arm/) in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.

A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding to an incoming `move` you can use the `bone` in that `move` to construct your response.

A `card` is the effect or event that is being requested. Each application should define the set of `cards` it can produce. Here is an excerpt from `clock.hoon` showing its `cards`

```hoon
+$  card
  $%  [%poke wire dock poke]
      [%http-response =http-event:http]
      [%connect wire binding:eyre term]
      [%diff %json json]
  ==
```

Each `card` is a pair of a tag and a [noun](/docs/glossary/noun/). The tag indicates what the event being triggered is and the [noun](/docs/glossary/noun/) is any data required for that event.

## Arms

Gall applications can have a number of arms that get called depending on the information they are sent.

### +on-init

This arm is called when the app is initially started.  It has no input and
lets you perform any initial IO.

### +on-save

This arm is called immediately before the agent is upgraded.  It
packages the permament state of the agent in a `vase` for the next version
of the agent.  Unlike most handlers, this cannot produce effects.

### +on-load

This arm is called immediately after the agent is upgraded.  It receives
{'fraction_non_alphanumeric': 0.08476394849785408, 'fraction_numerical': 0.0017167381974248926, 'mean_word_length': 3.8857442348008386, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1517613', 'n_tokens_mistral': 1365, 'n_tokens_neox': 1316, 'n_words': 708}