⌂ Modules nupp nupp.gpu nupp.gpunupp.gpu manages resident compute buffers over the selected GPU provider.
The context owns every buffer, compiled kernel and binding made from it. Each is closeable and borrows the context, so checked code cannot close the device while one is live, or use one after closing it. Uploads, dispatches, and downloads only enqueue commands; synchronize() is the explicit CPU boundary. gpu.available() says whether a device can be opened at all, since open raises when none can.
local gpu = nupp . gpu local array = nupp . mem . array local kernels = require ( "kernels" )
with context = gpu . open ( ) do
with input = context : buffer ( array . float , 1024 ) , output = context : buffer ( array . float , 1024 ) do
with kernel = kernels . scale : compile ( context ) do
with scale = kernel : bind ( output , input ) do
context : upload ( input , values : read ( ) )
scale : dispatch ( 2.0 )
end
end
context : enqueueDownload ( output )
context : synchronize ( )
context : readDownloaded ( output , result : write ( ) )
end
end Here kernels.scale is generated from an @aot(target = "gpu") function by a target with aot = "require". Shader source, entrypoint identity, binding order and uniform packing remain compiler details. Ordinary spans are the CPU boundary; a chain of kernels keeps its intermediate buffers resident and pays upload/download only where the program asks for them.
context:tensor(element, shape) allocates dense row-major storage. A checked gpu.Layout can be sliced, transposed, broadcast, or explicitly strided, then applied with buffer:view(layout) without allocating device storage. Transfers remain dense; layout-aware kernels consume the explicit metadata.
Submodules Module Description nupp.gpu.layoutWhere an element of a tensor actually is. nupp.gpu.spiShared interfaces for resident GPU implementations.
Module contents Types Type Kind Description Bufferinterface Typed resident device storage or a view borrowing its owning context. Contextinterface Device operations shared by application and provider contexts. Layoutrecord Phasesinterface Sharedinterface
Functions Function Kind Description availablefunction Reports whether the selected provider can open a compute device now. openfunction Opens a compute device through the selected provider. workgroupsfunction Executes uniformly ordered workgroup phases on the CPU.
Values Types
Bufferinterface Typed resident device storage or a view borrowing its owning context.
Type parameters
Members Name Kind Description closemethod Releases a root buffer's allocation, or ends a view, without suspending. countfield Number of logical elements in this buffer or view. dimensionsmethod Returns the logical shape in elements. stridesmethod Returns the element strides for the logical view. subviewmethod Creates a context-borrowed view at a zero-based origin with the requested shape. layoutmethod Returns the canonical tensor layout for this view. isDensemethod Reports whether this buffer or view occupies a dense element range. isInjectivemethod Reports whether every logical element maps to a distinct storage element. viewmethod Creates a view using the supplied checked layout without copying storage.
closemethod Releases a root buffer's allocation, or ends a view, without suspending.
Arguments Name Type Description takes selfBuffer < T >
Returns
countfield @readonly
Number of logical elements in this buffer or view.
dimensionsmethod dimensions : function ( borrows self : Buffer < T > ) : { integer } @readonly
Returns the logical shape in elements.
Arguments Name Type Description borrows selfBuffer < T >
Returns
stridesmethod strides : function ( borrows self : Buffer < T > ) : { integer } @readonly
Returns the element strides for the logical view.
Arguments Name Type Description borrows selfBuffer < T >
Returns
subviewmethod @readonly
Creates a context-borrowed view at a zero-based origin with the requested shape.
Arguments Name Type Description borrows selfBuffer < T > origin{ integer } shape{ integer }
Returns
layoutmethod @readonly
Returns the canonical tensor layout for this view.
Arguments Name Type Description borrows selfBuffer < T >
Returns Type Description TensorLayout
isDensemethod isDense : function ( borrows self : Buffer < T > ) : boolean @readonly
Reports whether this buffer or view occupies a dense element range.
Arguments Name Type Description borrows selfBuffer < T >
Returns
isInjectivemethod isInjective : function ( borrows self : Buffer < T > ) : boolean @readonly
Reports whether every logical element maps to a distinct storage element. A false result also covers a stride proof that was inconclusive.
Arguments Name Type Description borrows selfBuffer < T >
Returns
viewmethod @readonly
Creates a view using the supplied checked layout without copying storage. The layout must fit within the root allocation.
Arguments Name Type Description borrows selfBuffer < T > layoutTensorLayout
Returns
Contextinterface Device operations shared by application and provider contexts.
Members Name Kind Description closemethod Consumes the context and releases all device resources without suspending. drivermethod Returns a diagnostic name for the selected device implementation. buffermethod Allocates a typed resident device buffer. tensormethod Allocates typed storage with the requested logical shape, its element named as buffer names it. uploadmethod Copies borrowed host-span data into a same-sized dense buffer or view. enqueueDownloadmethod Queues a dense buffer or view readback for synchronization and reading. synchronizemethod Waits for queued device work and readbacks to complete. readDownloadedmethod Copies a synchronized readback into a same-sized exclusive destination. downloadmethod Queues, synchronizes, and copies a dense readback into the destination.
closemethod Consumes the context and releases all device resources without suspending.
Arguments Name Type Description takes selfContext
Returns
drivermethod driver : function ( borrows self : Context ) : string @readonly
Returns a diagnostic name for the selected device implementation.
Arguments Name Type Description borrows selfContext
Returns
buffermethod buffer : function < T > (
borrows self : Context ,
element : Scalar < T > | Type < T > ,
count : integer
) : affine ( gpu . Buffer < T > ) borrows ( self ) @readonly
Allocates a typed resident device buffer. The element is named by its array witness, such as nupp.mem.array.float, or by a struct declaration.
Arguments Name Type Description borrows selfContext elementScalar < T > | Type < T > countinteger
Returns
tensormethod @readonly
Allocates typed storage with the requested logical shape, its element named as buffer names it.
Arguments Name Type Description borrows selfContext elementScalar < T > | Type < T > shape{ integer }
Returns
uploadmethod upload : function < T > (
borrows self : Context ,
borrows buffer : gpu . Buffer < T > ,
borrows source : Span < T >
) : nil @readonly
Copies borrowed host-span data into a same-sized dense buffer or view.
Arguments Name Type Description borrows selfContext borrows buffergpu . Buffer < T > borrows sourceSpan < T >
Returns
enqueueDownloadmethod enqueueDownload : function < T > ( borrows self : Context , borrows buffer : gpu . Buffer < T > ) : nil @readonly
Queues a dense buffer or view readback for synchronization and reading.
Arguments Name Type Description borrows selfContext borrows buffergpu . Buffer < T >
Returns
synchronizemethod synchronize : function ( borrows self : Context ) : nil @readonly
Waits for queued device work and readbacks to complete.
Arguments Name Type Description borrows selfContext
Returns
readDownloadedmethod readDownloaded : function < T > (
borrows self : Context ,
borrows buffer : gpu . Buffer < T > ,
exclusive destination : WriteSpan < T >
) : nil @readonly
Copies a synchronized readback into a same-sized exclusive destination.
Arguments Name Type Description borrows selfContext borrows buffergpu . Buffer < T > exclusive destinationWriteSpan < T >
Returns
downloadmethod download : function < T > (
borrows self : Context ,
borrows buffer : gpu . Buffer < T > ,
exclusive destination : WriteSpan < T >
) : nil @readonly
Queues, synchronizes, and copies a dense readback into the destination.
Arguments Name Type Description borrows selfContext borrows buffergpu . Buffer < T > exclusive destinationWriteSpan < T >
Returns
Layoutrecord Members Name Kind Description countfield offsetmethod The element offset of the layout's first element. extentmethod One more than the largest element offset the layout reaches, measured from its first element. dimensionsmethod The logical shape. stridesmethod The element stride of each dimension. isDensemethod Reports whether the elements occupy a dense row-major range. isInjectivemethod Reports whether the layout's strides prove that element offsets are distinct.
offsetmethod offset : function offset ( borrows self ) : integer The element offset of the layout's first element.
Arguments Name Type Description borrows selfany
Returns
extentmethod extent : function extent ( borrows self ) : integer One more than the largest element offset the layout reaches, measured from its first element.
Arguments Name Type Description borrows selfany
Returns
dimensionsmethod dimensions : function dimensions ( borrows self ) : { integer } The logical shape. The returned table is a copy.
Arguments Name Type Description borrows selfany
Returns
stridesmethod strides : function strides ( borrows self ) : { integer } The element stride of each dimension. The returned table is a copy.
Arguments Name Type Description borrows selfany
Returns
isDensemethod isDense : function isDense ( borrows self ) : boolean Reports whether the elements occupy a dense row-major range.
Arguments Name Type Description borrows selfany
Returns
isInjectivemethod isInjective : function isInjective ( borrows self ) : boolean Reports whether the layout's strides prove that element offsets are distinct.
A false result also covers layouts for which the bounded stride proof is inconclusive.
Arguments Name Type Description borrows selfany
Returns
Phasesinterface Members Name Kind Description scratchmethod Allocates fresh zero-based scratch for this workgroup. runmethod Runs a stage to completion in ascending local-index order. reduceSummethod Reduces one power-of-two f32 workgroup in a fixed left-before-right tree. inclusiveScanmethod Computes a deterministic inclusive u32 prefix sum.
scratchmethod scratch : function < T > ( borrows self : Phases , initial : T , count : integer ) : gpu . Shared < T > @readonly
Allocates fresh zero-based scratch for this workgroup.
Arguments Name Type Description borrows selfPhases initialT countinteger
Returns
runmethod run : function ( borrows self : Phases , scoped stage : function ( uint32 ) : nil ) : nil @readonly
Runs a stage to completion in ascending local-index order.
Arguments Name Type Description borrows selfPhases scoped stagefunction ( uint32 ) : nil
Returns
reduceSummethod reduceSum : function ( borrows self : Phases , exclusive values : gpu . Shared < float > ) : nil @readonly
Reduces one power-of-two f32 workgroup in a fixed left-before-right tree. The sum is left in element zero.
Arguments Name Type Description borrows selfPhases exclusive valuesgpu . Shared < float >
Returns
inclusiveScanmethod @readonly
Computes a deterministic inclusive u32 prefix sum. temporary is a same-sized scratch array used for disjoint ping-pong stages; the result is left in values.
Arguments
Returns
Sharedinterface Type parameters
__lenmetamethod __len : function ( borrows self : Shared < T > ) : integer Arguments Name Type Description borrows selfShared < T >
Returns
__indexmetamethod __index : function ( borrows self : Shared < T > , index : integer ) : T Arguments Name Type Description borrows selfShared < T > indexinteger
Returns
__newindexmetamethod __newindex : function ( exclusive self : Shared < T > , index : integer , value : T ) : nil Arguments Name Type Description exclusive selfShared < T > indexinteger valueT
Returns
Functions
availablefunction Reports whether the selected provider can open a compute device now.
open raises when none can, and with needs the context it returns, so ask this first where a program has another way to run. Answering it opens and closes a device.
Returns
openfunction Opens a compute device through the selected provider.
Returns
workgroupsfunction Executes uniformly ordered workgroup phases on the CPU.
A GPU AOT body recognizes this call and its immediate callbacks as structure: the controller does not escape, each run is a device barrier, and each stage invocation becomes one local lane. It runs groups groups, 0 through groups - 1, and the device runs the same ones: the kernel's required u32.div(#span, size) never visits a partial group.
Arguments
Returns
Raises Type Condition string when size is outside the portable workgroup limit
Values
PORTABLE_SCRATCH_BYTESvariable PORTABLE_WORKGROUP_THREADSvariable ← Previous nupp.events Next → nupp.gpu.layout