packages/@greenpandastudios/aug-gpu/0.2.0/api.aug
GPU workers · Dependency source and specification
This is the exact dependency version used by this example.
Code
// Generated by aug spec. This is a copy of the installed dependency source.
// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
import Device and Buffer from bindings
import GpuError from contracts
extern C _open() returns own Device unless GpuError
extern C _upload(Device device, List<float> values) returns own Buffer unless GpuError
extern C _add(Buffer left, Buffer right) returns own Buffer unless GpuError
extern C _download(Buffer buffer) returns List<float> unless GpuError
extern C _live() returns int
/** Open a Metal GPU on the current worker. No device means GpuError. */
openDevice() returns own Device:
unsafe:
return _open()
/** Copy finite numbers to an owned float32 GPU buffer. Values round to float32. */
upload(Device device, List<float> values) returns own Buffer:
unsafe:
return _upload(device, values)
/** Add equally sized buffers on the GPU. Wait for device completion before returning. */
add(Buffer left, Buffer right) returns own Buffer:
unsafe:
return _add(left, right)
/** Copy float32 GPU values into an August list of floats. */
download(Buffer buffer):
unsafe:
return _download(buffer)
test openDevice:
when "metal":
it "adds_on_the_gpu_and_releases_every_resource":
int before = 0
unsafe:
before = _live()
scope:
own Device device = openDevice()
own Buffer left = upload(device, values=[1.0, 2.0, 3.0])
own Buffer right = upload(device, values=[4.0, 5.0, 6.0])
own Buffer result = add(left, right)
output = download(buffer=result)
assert(output.get(index=0) == 5.0)
assert(output.get(index=1) == 7.0)
assert(output.get(index=2) == 9.0)
unsafe:
assert(_live() == before)
it "cleans_up_when_an_operation_fails":
try:
scope:
own Device device = openDevice()
own Buffer left = upload(device, values=[1.0])
own Buffer right = upload(device, values=[2.0, 3.0])
own Buffer result = add(left, right)
assert(false)
catch GpuError error:
assert(error.code == 2)
unsafe:
assert(_live() == 0)// Generated by aug spec. This is a copy of the installed dependency source.
// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
import Device and Buffer from bindings
import GpuError from contracts
extern C _open() returns own Device unless GpuError
extern C _upload(Device device, List<float> values) returns own Buffer unless GpuError
extern C _add(Buffer left, Buffer right) returns own Buffer unless GpuError
extern C _download(Buffer buffer) returns List<float> unless GpuError
extern C _live() returns int
/** Open a Metal GPU on the current worker. No device means GpuError. */
openDevice() returns own Device {
unsafe {
return _open()
}
}
/** Copy finite numbers to an owned float32 GPU buffer. Values round to float32. */
upload(Device device, List<float> values) returns own Buffer {
unsafe {
return _upload(device, values)
}
}
/** Add equally sized buffers on the GPU. Wait for device completion before returning. */
add(Buffer left, Buffer right) returns own Buffer {
unsafe {
return _add(left, right)
}
}
/** Copy float32 GPU values into an August list of floats. */
download(Buffer buffer) {
unsafe {
return _download(buffer)
}
}
test openDevice {
when "metal" {
it "adds_on_the_gpu_and_releases_every_resource" {
int before = 0
unsafe {
before = _live()
}
scope {
own Device device = openDevice()
own Buffer left = upload(device, values=[1.0, 2.0, 3.0])
own Buffer right = upload(device, values=[4.0, 5.0, 6.0])
own Buffer result = add(left, right)
output = download(buffer=result)
assert(output.get(index=0) == 5.0)
assert(output.get(index=1) == 7.0)
assert(output.get(index=2) == 9.0)
}
unsafe {
assert(_live() == before)
}
}
it "cleans_up_when_an_operation_fails" {
try {
scope {
own Device device = openDevice()
own Buffer left = upload(device, values=[1.0])
own Buffer right = upload(device, values=[2.0, 3.0])
own Buffer result = add(left, right)
assert(false)
}
}
catch GpuError error {
assert(error.code == 2)
}
unsafe {
assert(_live() == 0)
}
}
}
}Compiled specification
openDevice · source
Open a Metal GPU on the current worker. No device means GpuError. It returns ownership of Device. Failures can raise GpuError.
Within an unsafe block, it returns _open. Native operations must satisfy their declared C contracts. source
Checked interface
openDevice() returns own Device unless GpuErrorIt returns ownership of Device. Failures can raise GpuError.
upload · source
Copy finite numbers to an owned float32 GPU buffer. Values round to float32. It takes device as Device and values as List<float>.
It returns ownership of Buffer. Failures can raise GpuError. Within an unsafe block, it returns _upload with device and values. Native operations must satisfy their declared C contracts. source
Checked interface
upload(Device device, List<float> values) returns own Buffer unless GpuErrorIt takes device as Device and values as List<float>. It returns ownership of Buffer. Failures can raise GpuError.
add · source
Add equally sized buffers on the GPU. Wait for device completion before returning. It takes left and right as Buffer.
It returns ownership of Buffer. Failures can raise GpuError. Within an unsafe block, it returns _add with left and right. Native operations must satisfy their declared C contracts. source
Checked interface
add(Buffer left, Buffer right) returns own Buffer unless GpuErrorIt takes left and right as Buffer. It returns ownership of Buffer. Failures can raise GpuError.
download · source
Copy float32 GPU values into an August list of floats. It takes buffer as Buffer. Failures can raise GpuError.
Within an unsafe block, it returns _download with buffer. Native operations must satisfy their declared C contracts. source
Checked interface
download(Buffer buffer) returns List<float> unless GpuError_open · source
It is private to its defining scope. It returns ownership of Device. Failures can raise GpuError.
Native implementation: @greenpandastudios/aug-gpu@0.2.0, 0.1.0. Supported targets: macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 d95e237d8be07df8fd20132ca0f5a45a125fd65b7ba93669e69c0a38db63d60c). It calls aug_gpu_open_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. The caller owns the returned handle. Its maintainer permits independent instances on worker threads. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
_upload · source
It is private to its defining scope. It takes device as Device and values as List<float>. It returns ownership of Buffer. Failures can raise GpuError.
Native implementation: @greenpandastudios/aug-gpu@0.2.0, 0.1.0. Supported targets: macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 d95e237d8be07df8fd20132ca0f5a45a125fd65b7ba93669e69c0a38db63d60c). It calls aug_gpu_upload_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. device lends read access for this call. The caller owns the returned handle. Its maintainer permits independent instances on worker threads. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
_add · source
It is private to its defining scope. It takes left and right as Buffer. It returns ownership of Buffer. Failures can raise GpuError.
Native implementation: @greenpandastudios/aug-gpu@0.2.0, 0.1.0. Supported targets: macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 d95e237d8be07df8fd20132ca0f5a45a125fd65b7ba93669e69c0a38db63d60c). It calls aug_gpu_add_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. left lends read access for this call; right lends read access for this call. The caller owns the returned handle. Its maintainer permits independent instances on worker threads. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
_download · source
It is private to its defining scope. It takes buffer as Buffer. It returns List<float>. Failures can raise GpuError.
Native implementation: @greenpandastudios/aug-gpu@0.2.0, 0.1.0. Supported targets: macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 d95e237d8be07df8fd20132ca0f5a45a125fd65b7ba93669e69c0a38db63d60c). It calls aug_gpu_download_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. buffer lends read access for this call. August copies the returned buffer, then calls aug_gpu_values_release_v1 to release it. Its maintainer permits independent instances on worker threads. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
_live · source
It is private to its defining scope. It returns int.
Native implementation: @greenpandastudios/aug-gpu@0.2.0, 0.1.0. Supported targets: macos arm64 14.0+. Binding contract: native.abi.json (SHA-256 d95e237d8be07df8fd20132ca0f5a45a125fd65b7ba93669e69c0a38db63d60c). It calls aug_gpu_live_resources_v1 through the C ABI on the caller thread; a blocking native call blocks that thread. Its maintainer permits independent instances on worker threads. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
test openDevice · source
Tests openDevice. Each case gets fresh setup and dependencies.
metal
It sets before to 0. Within an unsafe block, it gets before from _live. Native operations must satisfy their declared C contracts. Within a task and ownership scope, it calls openDevice and stores the result in owned device (Device). source
It calls upload with device and values from a list containing 1.0, 2.0, 3.0 and stores the result in owned left (Buffer). It calls upload with device and values from a list containing 4.0, 5.0, 6.0 and stores the result in owned right (Buffer). It calls add with left and right and stores the result in owned result (Buffer). It sets output to download with buffer from result. source
The test requires output.get with index 0 equals 5.0. The test requires output.get with index 1 equals 7.0. The test requires output.get with index 2 equals 9.0. On leaving this scope, join its child tasks and release its local values. source
Within an unsafe block, the test requires _live equals before. Native operations must satisfy their declared C contracts. source
Within a task and ownership scope, it calls openDevice and stores the result in owned device (Device). It calls upload with device and values from a list containing 1.0 and stores the result in owned left (Buffer). It calls upload with device and values from a list containing 2.0, 3.0 and stores the result in owned right (Buffer). It calls add with left and right and stores the result in owned result (Buffer). source
The test requires false is true. On leaving this scope, join its child tasks and release its local values. If this work raises GpuError as error, it the test requires error.code equals 2. Within an unsafe block, the test requires _live equals 0. source
Native operations must satisfy their declared C contracts. source
Dependencies
It uses Buffer and Device from bindings. It uses GpuError from contracts.
Built-in operations follow the language reference.