`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.

Module contents

Types

Type	Kind	Description
`ArtifactSet`	record	Generated shader formats and entrypoint accepted by provider compilation.
`Binding`	interface	Canonical kernel invocation with buffer slots and uniform dispatch.
`Buffer`	interface	Canonical typed resident buffer/view borrowing its context.
`Context`	interface	Complete shared context protocol, including generated-kernel operations.
`ContextToken`	interface	Shared non-suspending context cleanup obligation.
`Kernel`	interface	Canonical opaque kernel handle borrowing its context.
`Provider`	interface

Functions

Function	Kind	Description
`destroyContext`	function	Shared affine cleanup identity; provider returns must preserve it.

Values

Value	Kind	Description
`service`	variable	Canonical host.gpu API 1 handle; setup selects before the public facade loads.

Types#

`ArtifactSet`record#

record ArtifactSet
    readonly spirv: string?
    readonly wgsl: string?
    readonly entrypoint: string
end

Generated shader formats and entrypoint accepted by provider compilation.

Fields

`spirv`#

spirv: string?

Optional SPIR-V artifact bytes.

`wgsl`#

wgsl: string?

Optional WGSL shader source.

`entrypoint`#

entrypoint: string

Name of the entry point within the supplied artifacts.

`Binding`interface#

interface Binding
    readonly count: integer
    readonly setRead: function<T>(
        borrows self: Binding,
        slot: integer,
        borrows buffer: gpu.Buffer<T>,
        matchCount: boolean
    ): nil
    readonly setWrite: function<T>(
        borrows self: Binding,
        slot: integer,
        borrows buffer: gpu.Buffer<T>,
        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`#

setRead: function<T>(
    borrows self: gpu.Binding,
    slot: integer,
    borrows buffer: gpu.Buffer<T>,
    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<T>`
`matchCount`	`boolean`

Returns

Type	Description
`nil`

`setWrite`#

setWrite: function<T>(
    borrows self: gpu.Binding,
    slot: integer,
    borrows buffer: gpu.Buffer<T>,
    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<T>`
`matchCount`	`boolean`

Returns

Type	Description
`nil`

`dispatchWords`#

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`#

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`#

count: integer

Number of logical elements dispatched.

`Buffer`interface#

interface Buffer<T>
    readonly count: integer
    readonly dimensions: function(borrows self: Buffer<T>): {integer}
    readonly strides: function(borrows self: Buffer<T>): {integer}
    readonly subview: function(
        borrows self: Buffer<T>,
        origin: {integer},
        shape: {integer}
    ): Buffer<T> borrows (self)
    readonly layout: function(borrows self: Buffer<T>): TensorLayout
    readonly view: function(borrows self: Buffer<T>, layout: TensorLayout): Buffer<T> borrows (self)
end

Canonical typed resident buffer/view borrowing its context.

Type parameters

Name	Description
`T`

Methods

`dimensions`#

dimensions: function(borrows self: gpu.Buffer<T>): {integer}

Returns the logical shape in elements.

Arguments

Name	Type	Description
`borrows self`	`gpu.Buffer<T>`

Returns

Type	Description
`{integer}`

`strides`#

strides: function(borrows self: gpu.Buffer<T>): {integer}

Returns the element strides for the logical view.

Arguments

Name	Type	Description
`borrows self`	`gpu.Buffer<T>`

Returns

Type	Description
`{integer}`

`subview`#

subview: function(
    borrows self: gpu.Buffer<T>,
    origin: {integer},
    shape: {integer}
): gpu.Buffer<T> borrows (self)

Creates a context-borrowed view at a zero-based origin with the requested shape.

Arguments

Name	Type	Description
`borrows self`	`gpu.Buffer<T>`
`origin`	`{integer}`
`shape`	`{integer}`

Returns

Type	Description
`gpu.Buffer<T> borrows (self)`

`layout`#

layout: function(borrows self: gpu.Buffer<T>): TensorLayout

Returns the canonical tensor layout for this view.

Arguments

Name	Type	Description
`borrows self`	`gpu.Buffer<T>`

Returns

Type	Description
`TensorLayout`

`view`#

view: function(borrows self: gpu.Buffer<T>, layout: TensorLayout): gpu.Buffer<T> borrows (self)

Creates a view using the supplied checked layout without copying storage.

Arguments

Name	Type	Description
`borrows self`	`gpu.Buffer<T>`
`layout`	`TensorLayout`

Returns

Type	Description
`gpu.Buffer<T> borrows (self)`

Fields

`count`#

count: integer

Number of elements, kept with the allocation.

`Context`interface#

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`#

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`#

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`#

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`#

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#

interface ContextToken
    readonly drop: nosuspend function(takes self: ContextToken): nil
end

Shared non-suspending context cleanup obligation.

Methods

`drop`#

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#

interface Kernel
end

Canonical opaque kernel handle borrowing its context.

`Provider`interface#

interface Provider
    readonly open: function(): affine(types.KernelContext, types.destroyContext)
end

Methods

`open`#

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#

function destroyContext<T is gpu.ContextToken>(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#

const service: services.Service<Provider>

Canonical host.gpu API 1 handle; setup selects before the public facade loads.

nupp.runtime.services.gpu

Module contents

Types

Functions

Values

Types#

ArtifactSetrecord#

Fields

spirv#

wgsl#

entrypoint#

Bindinginterface#

Methods

setRead#

Arguments

Returns

setWrite#

Arguments

Returns

dispatchWords#

Arguments

Returns

dispatchPacked#

Arguments

Returns

Fields

count#

Bufferinterface#

Type parameters

Methods

dimensions#

Arguments

Returns

strides#

Arguments

Returns

subview#

Arguments

Returns

layout#

Arguments

Returns

view#

Arguments

Returns

Fields

count#

Contextinterface#

Methods

compileGenerated#

Arguments

Returns

bindKernel#

Arguments

Returns

releaseKernel#

Arguments

Returns

releaseBinding#

Arguments

Returns

ContextTokeninterface#

Methods

drop#

Arguments

Returns

Kernelinterface#

Providerinterface#

Methods

open#

Returns

Functions#

destroyContextfunction#

Type parameters

Arguments

Returns

Values#

servicevariable#

`nupp.runtime.services.gpu`

`ArtifactSet`record#

`spirv`#

`wgsl`#

`entrypoint`#

`Binding`interface#

`setRead`#

`setWrite`#

`dispatchWords`#

`dispatchPacked`#

`count`#

`Buffer`interface#

`dimensions`#

`strides`#

`subview`#

`layout`#

`view`#

`count`#

`Context`interface#

`compileGenerated`#

`bindKernel`#

`releaseKernel`#

`releaseBinding`#

`ContextToken`interface#

`drop`#

`Kernel`interface#

`Provider`interface#

`open`#

`destroyContext`function#

`service`variable#