# `nupp.host.pump` `nupp.host.pump` runs one operation at a time for an application that embeds the runtime and owns its own loop. Reach for it from the exports such an application calls, so that an operation which waits -- on a `nupp.host` request, a timer, the network -- parks instead of blocking the call that started it. `start` runs an operation until it finishes or parks, and says which; the application keeps calling `poll` from its loop, after answering whatever it was asked, until the operation finishes. Each poll is one non-blocking pass over the runtime's readiness sources, and an operation they make ready resumes inside that pass. ```nupp:fragment local pump = nupp.host.pump local session = pump.newPump() export function frame(dt: number): pump.State if session:parked() then return session:poll() end return session:start(function(): boolean return update(dt) end) end ``` An operation returns whether the application should keep running: `false` reports `"stopped"`, anything else `"continue"`. A failure is raised from the `start` or `poll` that observes it. `cancel` unwinds a parked operation, raising a [cancellation](../../../../learn/runtime/concurrency/suspension/index.html) inside it, so its cleanup runs before the application shuts down. ## Types ### `Pump` _record_ ```nupp record Pump ... ``` Runs one parked operation at a time for a host-owned loop. #### Members | Name | Kind | Description | | --- | --- | --- | | [`handler`](#nupp.host.pump.Pump.handler) | field | | | [`active`](#nupp.host.pump.Pump.active) | field | | | [`result`](#nupp.host.pump.Pump.result) | field | | | [`failure`](#nupp.host.pump.Pump.failure) | field | | | [`start`](#nupp.host.pump.Pump.start) | method | Runs body until it finishes or parks. | | [`poll`](#nupp.host.pump.Pump.poll) | method | Makes one non-blocking pass over the readiness sources, resuming the parked operation if they make it ready. | | [`parked`](#nupp.host.pump.Pump.parked) | method | Whether an operation is parked between the host's turns. | | [`cancel`](#nupp.host.pump.Pump.cancel) | method | Unwinds a parked operation, raising a cancellation inside it. | #### `handler` _field_ ```nupp handler: suspensionContract.Handler ``` `@private` #### `active` _field_ ```nupp active: thread? ``` `@private` #### `result` _field_ ```nupp result: boolean? ``` `@private` #### `failure` _field_ ```nupp failure: any? ``` `@private` #### `start` _method_ ```nupp start: function start(self: Pump, body: function(): boolean?): State ``` Runs `body` until it finishes or parks. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pump` | | | `body` | `function(): boolean?` | | ##### Returns | Type | Description | | --- | --- | | `State` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when another operation is still parked, or what `body` raised | #### `poll` _method_ ```nupp poll: function poll(self: Pump): State ``` Makes one non-blocking pass over the readiness sources, resuming the parked operation if they make it ready. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pump` | | ##### Returns | Type | Description | | --- | --- | | `State` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when nothing is parked, or what the operation raised | #### `parked` _method_ ```nupp parked: function parked(self: Pump): boolean ``` Whether an operation is parked between the host's turns. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pump` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `cancel` _method_ ```nupp cancel: function cancel(self: Pump): nil ``` Unwinds a parked operation, raising a cancellation inside it. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pump` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the operation does not unwind | ### `State` _type_ ```nupp type State = "parked" | "continue" | "stopped" ``` What a `start` or `poll` left the operation doing. ## Functions ### `newPump` _function_ ```nupp function newPump(): Pump ``` Creates an idle pump. #### Returns | Type | Description | | --- | --- | | `Pump` | |