ExCubecl — GPU compute runtime for Elixir.
Provides GPU buffer management, kernel execution, async command submission, and pipeline orchestration via CubeCL (Rust NIFs).
Quick start
# Check availability
ExCubecl.available?()
# Create a buffer from a list
{:ok, buf} = ExCubecl.buffer([1.0, 2.0, 3.0], [3], :f32)
# Inspect
{:ok, shape} = ExCubecl.shape(buf) # [3]
{:ok, dtype} = ExCubecl.dtype(buf) # "f32"
{:ok, size} = ExCubecl.size(buf) # 12 (bytes)
# Read back
{:ok, binary} = ExCubecl.read(buf)
# Free when done
ExCubecl.free(buf)Kernel execution
{:ok, out} = ExCubecl.buffer([0.0, 0.0, 0.0], [3], :f32)
ExCubecl.run_kernel("elementwise_add", [buf_a, buf_b], out)Async commands
{:ok, cmd} = ExCubecl.submit("some_command")
{:ok, :completed} = ExCubecl.poll(cmd)
:ok = ExCubecl.wait(cmd)Pipelines
{:ok, p} = ExCubecl.pipeline()
:ok = ExCubecl.pipeline_add(p, "elementwise_add:1,2:3")
:ok = ExCubecl.pipeline_run(p)
:ok = ExCubecl.pipeline_free(p)Summary
Functions
Checks if the NIF library is loaded and available.
Creates a GPU buffer from a list of values.
Creates a GPU buffer, raising on error.
Returns the number of available GPU devices.
Returns information about the GPU compute device.
Returns the dtype string of a buffer (e.g. "f32").
Frees a GPU buffer.
Returns the list of available kernel names.
Creates a new empty pipeline.
Adds a command to a pipeline.
Frees a pipeline and its resources.
Runs all commands in a pipeline sequentially.
Polls the status of an async command.
Reads buffer data back from the GPU as a binary.
Reads buffer data back, raising on error.
Runs a kernel on the GPU.
Returns the shape of a buffer.
Returns the byte size of a buffer.
Submits a command for asynchronous execution.
Returns the list of supported dtype atoms.
Returns the version of ExCubecl.
Blocks until an async command completes.
Functions
@spec available?() :: boolean()
Checks if the NIF library is loaded and available.
Returns true if the NIF can be loaded, false otherwise.
@spec buffer(list(), [non_neg_integer()], atom()) :: {:ok, non_neg_integer()} | {:error, term()}
Creates a GPU buffer from a list of values.
Parameters
data— a flat list of numbersshape— the tensor shape (e.g.[3]for a vector,[2, 3]for a matrix)type— element type, one of::f32,:f64,:s32,:s64,:u32,:u8(default:f32)
Returns
{:ok, buffer_id} on success, {:error, reason} on failure.
@spec buffer!(list(), [non_neg_integer()], atom()) :: non_neg_integer()
Creates a GPU buffer, raising on error.
See buffer/3 for parameters.
@spec device_count() :: {:ok, non_neg_integer()} | {:error, term()}
Returns the number of available GPU devices.
Returns information about the GPU compute device.
@spec dtype(non_neg_integer()) :: {:ok, String.t()} | {:error, term()}
Returns the dtype string of a buffer (e.g. "f32").
@spec free(non_neg_integer()) :: :ok | {:error, term()}
Frees a GPU buffer.
Returns the list of available kernel names.
@spec pipeline() :: {:ok, non_neg_integer()} | {:error, term()}
Creates a new empty pipeline.
@spec pipeline_add(non_neg_integer(), String.t()) :: :ok | {:error, term()}
Adds a command to a pipeline.
Command format: "kernel_name:input_id,input_id,...:output_id"
Example: "elementwise_add:1,2:3"
@spec pipeline_free(non_neg_integer()) :: :ok | {:error, term()}
Frees a pipeline and its resources.
@spec pipeline_run(non_neg_integer()) :: {:ok, [non_neg_integer()]} | {:error, term()}
Runs all commands in a pipeline sequentially.
@spec poll(non_neg_integer()) :: {:ok, :pending | :running | :completed | :failed} | {:error, term()}
Polls the status of an async command.
Returns {:ok, :pending | :running | :completed | :failed} or {:error, reason}.
@spec read(non_neg_integer()) :: {:ok, binary()} | {:error, term()}
Reads buffer data back from the GPU as a binary.
@spec read!(non_neg_integer()) :: binary()
Reads buffer data back, raising on error.
@spec run_kernel(String.t(), [non_neg_integer()], non_neg_integer(), map()) :: {:ok, non_neg_integer()} | {:error, term()}
Runs a kernel on the GPU.
Parameters
name— kernel name string (seekernels/0)inputs— list of input buffer IDsoutput— output buffer IDparams— optional map of kernel parameters (default%{})
@spec shape(non_neg_integer()) :: {:ok, [non_neg_integer()]} | {:error, term()}
Returns the shape of a buffer.
@spec size(non_neg_integer()) :: {:ok, non_neg_integer()} | {:error, term()}
Returns the byte size of a buffer.
@spec submit(String.t()) :: {:ok, non_neg_integer()} | {:error, term()}
Submits a command for asynchronous execution.
Returns {:ok, command_id} which can be used with poll/1 and wait/1.
@spec supported_dtypes() :: [atom()]
Returns the list of supported dtype atoms.
@spec version() :: String.t()
Returns the version of ExCubecl.
@spec wait(non_neg_integer()) :: :ok | {:error, term()}
Blocks until an async command completes.