Getting Started

ExCubecl is a GPU compute runtime for Elixir, powered by CubeCL via Rust NIFs. The current release (v0.5.0) includes a compiled Rust NIF with CPU-side kernel implementations that simulate the CubeCL API surface.

Installation

Add to your mix.exs:

def deps do
  [{:ex_cubecl, "~> 0.5"}]
end

Then run mix deps.get.

Architecture

Elixir → ExCubecl.NIF → Rust NIF → CPU-side kernel execution

All resource state lives in Rust-managed memory via ResourceArc. The Elixir side manages handles, orchestrates pipelines, and exposes command-style APIs. Kernels execute CPU-side implementations of the CubeCL API surface. Media I/O, transcoding, and video/audio operations use a mix of NIF-backed implementations and Elixir-level validation.

Core Concepts

Buffers

Buffers are the primary data structure, representing typed, shaped data in CPU-side resource memory:

# Create a buffer from a list
{:ok, buf} = ExCubecl.buffer([1.0, 2.0, 3.0], [3], :f32)

# Inspect
{:ok, [3]} = ExCubecl.shape(buf)
{:ok, "f32"} = ExCubecl.dtype(buf)
{:ok, 12} = ExCubecl.size(buf)   # bytes

# Read data back
{:ok, data} = ExCubecl.read(buf)

# Buffers are automatically freed when the Elixir term is garbage collected.

Kernels

Kernels are exposed through the CubeCL-style API and execute CPU-side in the Rust NIF:

{:ok, input} = ExCubecl.buffer([1.0, 2.0, 3.0], [3], :f32)
{:ok, output} = ExCubecl.buffer([0.0, 0.0, 0.0], [3], :f32)

{:ok, _cmd} = ExCubecl.run_kernel("elementwise_add", [input], output)

Async Execution

Submit command-style work without blocking the BEAM:

{:ok, cmd_id} = ExCubecl.submit("some_command")

# Poll for status
{:ok, :completed} = ExCubecl.poll(cmd_id)

# Or block until done
:ok = ExCubecl.wait(cmd_id)

Pipelines

Compose multiple kernel operations into a single executable graph:

{:ok, pipeline} = ExCubecl.pipeline()

:ok = ExCubecl.pipeline_add(pipeline, "elementwise_add", [buf_a, buf_b], buf_out)
:ok = ExCubecl.pipeline_add(pipeline, "relu", [buf_out], buf_result)

{:ok, _cmd_ids} = ExCubecl.pipeline_run(pipeline)
:ok = ExCubecl.pipeline_free(pipeline)

Supported Types

Checking Availability

ExCubecl.available?()    # true if NIF is loaded
ExCubecl.version()       # returns the ExCubecl module version (e.g. "0.5.0")
ExCubecl.device_info()   # NIF device metadata (device_type: "gpu", total_memory, compute_units)
ExCubecl.device_count()  # number of available devices

Next Steps

• Buffer Management — creating, reading, and inspecting buffers
• Kernel Execution — running kernels via the NIF
• Async & Pipelines — command-style APIs and pipeline orchestration
• Mobile Integration — iOS/Android C header prototype
• Examples — API examples