Pipeline Creation Result#

The pipelining API creates host-side pipeline objects before launching kernels. Creation functions return an expected result so callers can handle recoverable validation and CUDA runtime failures without relying on assertions.

Creation Return Type#

suggest_pipeline and make_pipeline return a non-movable cublasdx::detail::expected<host_pipeline, pipeline_error> object.

API	Meaning
`if(pipeline) { ... }`	Enters the success branch when a usable host pipeline was created.
`if(not pipeline) { ... }`	Enters the error branch when pipeline creation failed.
`pipeline->buffer_alignment()`	Required dynamic shared-memory alignment for the device pipeline storage.
`pipeline->buffer_size()`	Required dynamic shared-memory bytes for the device pipeline storage.
`pipeline->get_block_dim()`	CUDA block configuration expected by this pipeline.
`pipeline->get_device_handle()`	Device-side pipeline handle to pass by value to the kernel.
`pipeline.error()`	Returns `cublasdx::pipeline_error` when creation fails.

`pipeline_error`#

cublasdx::pipeline_error stores the cuBLASDx validation reason and, when applicable, a CUDA runtime status.

Diagram showing pipeline_error_code separately from CUDA runtime status in cublasdx::pipeline_error.

auto pipeline = cublasdx::suggest_pipeline<BLAS>(global_a, global_b);
if(not pipeline) {
    auto const& error = pipeline.error();
    if (error.code != cublasdx::pipeline_error_code::none) {
        std::cout << cublasdx::pipeline_error_string(error.code);
    }
    if (error.get_cuda_error() != cudaSuccess) {
        std::cout << cudaGetErrorString(error.get_cuda_error());
    }
}

Member	Meaning
`pipeline_error::code`	A `cublasdx::pipeline_error_code` value describing a cuBLASDx validation or allocation failure, `cuda` for a CUDA-only preprocessing failure, or `unknown` for an unclassified cuBLASDx failure.
`pipeline_error::get_cuda_error()`	CUDA runtime status associated with allocation or emulation preprocessing. In NVRTC builds this returns the stored integer status.

Emulation preprocessing can fail after cuBLASDx validation succeeds. In that case, code == pipeline_error_code::cuda and the CUDA runtime status is reported through get_cuda_error(). Always inspect both fields when reporting a pipeline creation failure.

`pipeline_error_code`#

Code	Meaning
`none`	No pipeline error code. A non-success CUDA status is normalized to `cuda` instead of `none`.
`incompatible_k_dimensions`	The A and B global tensors do not have the same `K` dimension.
`tile_divisibility`	The global `M`, `N`, or `K` dimension is not divisible by the BLAS tile size from `Size<M, N, K>`.
`insufficient_stages`	The global `K` dimension does not provide enough `K` tiles for the requested pipeline depth.
`emulation_k_dimension_too_large`	A flexible-precision emulation pipeline has `K > 33025` which is the internal upper limit to avoid overflow. Emulation slices inputs to `int8` and accumulates products of sliced 8-bit values in an internal `int32` GEMM path; use split-K for larger emulation problems.
`allocation_failed`	Temporary host-side allocation for flexible-precision emulation failed. Check `get_cuda_error()` for the CUDA status.
`unknown`	Reserved fallback for an unclassified cuBLASDx failure.
`cuda`	CUDA runtime failure with no more specific cuBLASDx pipeline error code. Check `get_cuda_error()` for the CUDA status.

`pipeline_error_string`#

cublasdx::pipeline_error_string(code) returns a stable human-readable string for each pipeline_error_code value. It is intended for diagnostics and logging; programmatic handling should switch on pipeline_error_code directly.