on master help sign in
Merge pull request #945 from urbit/ames-plea-gift
6d2dd68David Kerschner
reference/vane-apis/ames.md+10−2
@@ -116,7 +116,7 @@ This `task` returns no `gift`s.
116
116
117### `%plea`
117### `%plea`
118
118
119−`%plea` is the `task` used to send messages over Ames. It extends the
119+`%plea` is the `task` used to instruct Ames to send a message. It extends the
120`%pass`/`%give` semantics across the network. As such, it is the most
120`%pass`/`%give` semantics across the network. As such, it is the most
121fundamental `task` in Ames and the primary reason for its existence.
121fundamental `task` in Ames and the primary reason for its existence.
122
122
@@ -124,6 +124,11 @@ Ames also `pass`es a `%plea` `note` to another vane when it receives a message o
124"forward flow" from a peer, originally passed from one of the peer's vanes to the
124"forward flow" from a peer, originally passed from one of the peer's vanes to the
125peer's Ames.
125peer's Ames.
126
126
127+Ultimately `%plea` causes `%send` `gift`(s) to be sent to Unix, which tells
128+Unix to send packets. In terms of `%pass`/`%give` semantics, this is in
129+response to the `%born` `task`, which came along the Unix `duct`, rather than a
130+response to the `%plea`.
131+
127#### Accepts
132#### Accepts
128
133
129```hoon
134```hoon
@@ -143,7 +148,6 @@ route on the receiving ship, and `payload` is the semantic message content.
143
148
144This `task` returns no `gift`s.
149This `task` returns no `gift`s.
145
150
146−
147## System and Lifecycle Tasks
151## System and Lifecycle Tasks
148
152
149### `%born`
153### `%born`
@@ -158,6 +162,10 @@ Each time you start your Urbit, the Arvo kernel calls the `%born` task for Ames.
158
162
159In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
163In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
160
164
165+The `duct` along which `%born` comes is Ames' only duct to Unix, so `%send`
166+`gift`s (which are instructions for Unix to send a packet) are also returned in
167+response to `%born`.
168+
161
169
162### `%crud`
170### `%crud`
163
171