# `nupp.runtime.services.gpu` Resident-compute provider contract for `host.gpu` API 1. Import `service` to register or select a device implementation before requiring `nupp.gpu`. `open` is a receiver-free function; it returns an affine KernelContext using the canonical `destroyContext` cleanup identity exported here. Implementations define private records satisfying the shared context, buffer, kernel, and binding interfaces. Reuse the exported types here rather than creating nominal substitutes. Context-bound buffers and kernels preserve their borrows, and cleanup preserves its non-suspending guarantees. Generated artifacts and layout facts constrain binding formats, counts, scalar uniforms, and target features. A provider may choose a compatible device, but it cannot change the representation compiled into a kernel. Device and artifact failures must be reported before incompatible operations are published or run. The facade exports the retained open function directly. ## Types ### `ArtifactSet` _record_ ```nupp record ArtifactSet readonly spirv: string? readonly wgsl: string? readonly entrypoint: string end ``` Generated shader formats and entrypoint accepted by provider compilation. #### Fields ##### `spirv` ```nupp spirv: string? ``` Optional SPIR-V artifact bytes. ##### `wgsl` ```nupp wgsl: string? ``` Optional WGSL shader source. ##### `entrypoint` ```nupp entrypoint: string ``` Name of the entry point within the supplied artifacts. ### `Binding` _interface_ ```nupp interface Binding readonly count: integer readonly setRead: function( borrows self: Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil readonly setWrite: function( borrows self: Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil readonly dispatchWords: function(borrows self: Binding, scalars: {uint32}): nil readonly dispatchPacked: function(borrows self: Binding, uniforms: any, uniformBytes: integer): nil end ``` Canonical kernel invocation with buffer slots and uniform dispatch. #### Methods ##### `setRead` ```nupp setRead: function( borrows self: gpu.Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil ``` Attaches a buffer to a zero-based read slot. matchCount requires one buffer element per dispatched element. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Binding` | | | `slot` | `integer` | | | `borrows buffer` | `gpu.Buffer\` | | | `matchCount` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `setWrite` ```nupp setWrite: function( borrows self: gpu.Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil ``` Attaches a buffer to a zero-based writable slot with the same count rule. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Binding` | | | `slot` | `integer` | | | `borrows buffer` | `gpu.Buffer\` | | | `matchCount` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `dispatchWords` ```nupp dispatchWords: function(borrows self: gpu.Binding, scalars: {uint32}): nil ``` Dispatches using the generated scalar uniform words. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Binding` | | | `scalars` | `{uint32}` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `dispatchPacked` ```nupp dispatchPacked: function(borrows self: gpu.Binding, uniforms: any, uniformBytes: integer): nil ``` Dispatches from the exact packed uniform layout and byte count. The provider must validate the byte count against the compiled kernel. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Binding` | | | `uniforms` | `any` | | | `uniformBytes` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields ##### `count` ```nupp count: integer ``` Number of logical elements dispatched. ### `Buffer` _interface_ ```nupp interface Buffer readonly count: integer readonly dimensions: function(borrows self: Buffer): {integer} readonly strides: function(borrows self: Buffer): {integer} readonly subview: function( borrows self: Buffer, origin: {integer}, shape: {integer} ): Buffer borrows (self) readonly layout: function(borrows self: Buffer): TensorLayout readonly view: function(borrows self: Buffer, layout: TensorLayout): Buffer borrows (self) end ``` Canonical typed resident buffer/view borrowing its context. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Methods ##### `dimensions` ```nupp dimensions: function(borrows self: gpu.Buffer): {integer} ``` Returns the logical shape in elements. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Buffer\` | | ###### Returns | Type | Description | | --- | --- | | `{integer}` | | ##### `strides` ```nupp strides: function(borrows self: gpu.Buffer): {integer} ``` Returns the element strides for the logical view. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Buffer\` | | ###### Returns | Type | Description | | --- | --- | | `{integer}` | | ##### `subview` ```nupp subview: function( borrows self: gpu.Buffer, origin: {integer}, shape: {integer} ): gpu.Buffer borrows (self) ``` Creates a context-borrowed view at a zero-based origin with the requested shape. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Buffer\` | | | `origin` | `{integer}` | | | `shape` | `{integer}` | | ###### Returns | Type | Description | | --- | --- | | `gpu.Buffer\ borrows (self)` | | ##### `layout` ```nupp layout: function(borrows self: gpu.Buffer): TensorLayout ``` Returns the canonical tensor layout for this view. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Buffer\` | | ###### Returns | Type | Description | | --- | --- | | `TensorLayout` | | ##### `view` ```nupp view: function(borrows self: gpu.Buffer, layout: TensorLayout): gpu.Buffer borrows (self) ``` Creates a view using the supplied checked layout without copying storage. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.Buffer\` | | | `layout` | `TensorLayout` | | ###### Returns | Type | Description | | --- | --- | | `gpu.Buffer\ borrows (self)` | | #### Fields ##### `count` ```nupp count: integer ``` Number of elements, kept with the allocation. ### `Context` _interface_ ```nupp interface Context is gpu.Context readonly compileGenerated: function( borrows self: Context, artifacts: gpu.ArtifactSet, readonlyBuffers: integer, writableBuffers: integer, uniformBytes: integer, threads: integer? ): gpu.Kernel borrows (self) readonly bindKernel: function( borrows self: Context, borrows kernel: gpu.Kernel, count: integer ): gpu.Binding borrows (self) readonly releaseKernel: function(borrows self: Context, borrows kernel: gpu.Kernel): nil readonly releaseBinding: function(borrows self: Context, exclusive binding: gpu.Binding): nil end ``` Complete shared context protocol, including generated-kernel operations. #### Methods ##### `compileGenerated` ```nupp compileGenerated: function( borrows self: gpu.KernelContext, artifacts: gpu.ArtifactSet, readonlyBuffers: integer, writableBuffers: integer, uniformBytes: integer, threads: integer? ): gpu.Kernel borrows (self) ``` Compiles compatible artifacts with exact read/write slot counts and uniform size. threads carries the generated workgroup requirement when specified. Reject unsupported layouts or device limits before returning a kernel. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.KernelContext` | | | `artifacts` | `gpu.ArtifactSet` | | | `readonlyBuffers` | `integer` | | | `writableBuffers` | `integer` | | | `uniformBytes` | `integer` | | | `threads` | `integer?` | | ###### Returns | Type | Description | | --- | --- | | `gpu.Kernel borrows (self)` | | ##### `bindKernel` ```nupp bindKernel: function( borrows self: gpu.KernelContext, borrows kernel: gpu.Kernel, count: integer ): gpu.Binding borrows (self) ``` Creates a binding for count elements using this context's compiled kernel. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.KernelContext` | | | `borrows kernel` | `gpu.Kernel` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `gpu.Binding borrows (self)` | | ##### `releaseKernel` ```nupp releaseKernel: function(borrows self: gpu.KernelContext, borrows kernel: gpu.Kernel): nil ``` Releases a compiled kernel; dependent bindings must no longer be used. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.KernelContext` | | | `borrows kernel` | `gpu.Kernel` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `releaseBinding` ```nupp releaseBinding: function(borrows self: gpu.KernelContext, exclusive binding: gpu.Binding): nil ``` Releases a binding while holding exclusive access to it. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `gpu.KernelContext` | | | `exclusive binding` | `gpu.Binding` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `ContextToken` _interface_ ```nupp interface ContextToken readonly drop: nosuspend function(takes self: ContextToken): nil end ``` Shared non-suspending context cleanup obligation. #### Methods ##### `drop` ```nupp drop: nosuspend function(takes self: ContextToken): nil ``` Consumes and releases the context without suspending. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `ContextToken` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `Kernel` _interface_ ```nupp interface Kernel end ``` Canonical opaque kernel handle borrowing its context. ### `Provider` _interface_ ```nupp interface Provider readonly open: function(): affine(types.KernelContext, types.destroyContext) end ``` #### Methods ##### `open` ```nupp open: function(): affine(types.KernelContext, types.destroyContext) ``` Opens an owned device context using the canonical destroyContext cleanup. Raise if the host cannot provide a compatible device. ###### Returns | Type | Description | | --- | --- | | `affine(types.KernelContext, types.destroyContext)` | | ## Functions ### `destroyContext` _function_ ```nupp function destroyContext(takes context: T): nil ``` Shared affine cleanup identity; provider returns must preserve it. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `takes context` | `T` | | #### Returns | Type | Description | | --- | --- | | `nil` | | ## Values ### `service` _variable_ ```nupp const service: services.Service ``` Canonical host.gpu API 1 handle; setup selects before the public facade loads.