@spec allocate_gpu(context(), [non_neg_integer()], atom()) ::
  {:ok, buffer()} | {:error, String.t()}

Allocates a GPU buffer with the given shape and type.

Returns an ExCubecl buffer reference.

@spec async_poll(command_id()) ::
  {:ok, :pending | :running | :completed | :failed} | {:error, term()}

Polls the status of an asynchronous command.

Returns :pending, :running, :completed, or :failed.

@spec async_submit(ExCubecl.Command.t()) :: {:ok, command_id()} | {:error, term()}

Submits a command for asynchronous execution.

Returns a command ID that can be polled or waited on.

@spec async_wait(command_id()) :: :ok | {:error, term()}

Blocks until the given command completes.

@spec available?() :: boolean()

Checks whether a GPU device is available via ExCubecl.

@spec available_backends() :: [backend()]

Returns a list of available GPU backends on this system.

Delegates to ExCubecl availability checks and platform detection.

@spec buffer_dtype(buffer()) :: {:ok, String.t()} | {:error, term()}

Returns the data type of a GPU buffer.

@spec buffer_read(buffer()) :: {:ok, binary()} | {:error, term()}

Reads the raw binary data from a GPU buffer.

@spec buffer_read!(buffer()) :: binary()

Reads the raw binary data from a GPU buffer, raising on error.

@spec buffer_shape(buffer()) :: {:ok, [non_neg_integer()]} | {:error, term()}

Returns the shape of a GPU buffer.

@spec buffer_size(buffer()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the size of a GPU buffer in bytes.

@spec compile_kernel(context(), kernel(), keyword()) ::
  {:ok, reference()} | {:error, String.t()}

Compiles a compute kernel for the given backend.

Kernels are managed by ExCubecl; this function verifies the kernel is available and returns a reference.

@spec destroy(context()) :: :ok

Destroys the GPU context and frees all associated resources.

@spec device_capabilities(context()) :: map()

Returns the capabilities of the GPU device.

@spec device_count() :: {:ok, non_neg_integer()} | {:error, term()}

Returns the number of GPU devices available.

@spec device_to_host(context(), buffer()) ::
  {:ok, Nx.Tensor.t()} | {:error, String.t()}

Copies data from a GPU buffer to host (CPU) as an Nx tensor.

Parameters

• ctx — The GPU context
• buffer — An ExCubecl buffer reference

Returns

{:ok, Nx.Tensor.t()} on success, {:error, reason} on failure.

@spec execute(context(), kernel(), [buffer()], keyword()) ::
  {:ok, buffer()} | {:error, String.t()}

Executes a compute kernel on the GPU.

Parameters

• ctx — The GPU context
• kernel — The kernel to execute (atom)
• args — List of ExCubecl buffer references
• opts — Options (currently unused, reserved for future use)

Returns

{:ok, result_buffer} on success, {:error, reason} on failure.

@spec free(context(), buffer()) :: :ok

Frees a GPU buffer.

Note: ExCubecl buffers are garbage-collected when their reference goes out of scope. This function is a no-op for API compatibility.

@spec host_to_device(context(), Nx.Tensor.t()) ::
  {:ok, buffer()} | {:error, String.t()}

Copies data from host (CPU) to a new GPU buffer.

Parameters

• ctx — The GPU context
• tensor — An Nx tensor to copy to the GPU

Returns

{:ok, buffer} on success, {:error, reason} on failure.

@spec init(
  backend(),
  keyword()
) :: {:ok, context()} | {:error, String.t()}

Initializes a GPU compute context for the given backend.

Parameters

• backend — The GPU backend to use (:cuda, :metal, :vulkan, :wgpu, :rocm)
• opts — Options (currently unused, reserved for future use)

Returns

{:ok, context} on success, {:error, reason} on failure.

@spec kernels() :: {:ok, [String.t()]} | {:error, term()}

Returns the list of kernel names supported by ExCubecl.

@spec memory_total(context()) :: non_neg_integer()

Returns the total available GPU memory (in bytes).

Note: ExCubecl does not currently expose memory usage statistics. This always returns 0.

@spec memory_used(context()) :: non_neg_integer()

Returns the amount of GPU memory currently in use (in bytes).

Note: ExCubecl does not currently expose memory usage statistics. This always returns 0.

@spec pipeline() :: {:ok, pipeline_id()} | {:error, term()}

Creates a new pipeline for multi-kernel execution.

@spec pipeline_add(pipeline_id(), atom(), [buffer()], buffer(), map()) ::
  :ok | {:error, term()}

Adds a kernel command to a pipeline.

Parameters

• pipeline_id — The pipeline to add to
• kernel — Kernel name (atom)
• inputs — List of input buffer references
• output — Output buffer reference
• params — Additional parameters (optional, default: %{})

@spec pipeline_add_struct(pipeline_id(), ExCubecl.Command.t()) ::
  :ok | {:error, term()}

Adds a pre-built %ExCubecl.Command{} struct to a pipeline.

@spec pipeline_free(pipeline_id()) :: :ok | {:error, term()}

Frees a pipeline and its associated resources.

@spec pipeline_run(pipeline_id()) :: {:ok, [command_id()]} | {:error, term()}

Executes all commands in the pipeline and returns their command IDs.

@spec supported_dtypes() :: [atom()]

Returns the list of supported data types.

@spec synchronize(context()) :: :ok

Synchronizes the GPU context, blocking until all queued operations complete.

Note: ExCubecl does not expose a global synchronization primitive. Use async_wait/1 on specific command IDs for fine-grained control.

@spec version() :: String.t()

Returns the ExCubecl library version string.