Chapter 08: Kernel Loading — load_kernel_source and load_kernel_library

The assembly problem

OpenCL compiles a single string of source code for each program. The string must be self-contained: all functions used by the kernel must be defined in the same string, in order, before they are called. There are no separate compilation units and no linker.

When a kernel needs dnorm4, and dnorm4 itself needs R_D__0 and R_finite, those definitions must precede dnorm4 in the string, which must precede the kernel body. opencltools provides two R functions that assemble and sort source components; use package = "nmathopencl" for this package’s inst/cl/ tree.

opencltools::load_kernel_source()

opencltools::load_kernel_source(relative_path, package = "nmathopencl")

Reads and returns the contents of a single .cl file from inst/cl/ inside the named package. The relative_path is relative to inst/cl/:

# Load the dnorm kernel entry-point file
kernel_src <- opencltools::load_kernel_source("src/dnorm_kernel.cl",
                                              package = "nmathopencl")

# Load a custom kernel from another package's inst/cl/
my_kernel   <- opencltools::load_kernel_source("ex_glmbayes_src/f2_f3_binomial_logit.cl",
                                   package = "nmathopencl")

The returned character string can be concatenated with a library string and passed to the C++ runner.

opencltools::load_kernel_library()

opencltools::load_kernel_library(subdir, package = "nmathopencl", verbose = FALSE)

Reads all .cl files from inst/cl/<subdir>/, parses the @provides / @depends annotations in each file, performs a topological sort, and returns a single concatenated source string with files in dependency-correct order.

# Load the complete nmath library (all ~180 files)
nmath_src <- opencltools::load_kernel_library("nmath", package = "nmathopencl")

# Load a smaller subset pre-curated for glmbayes kernels
nmath_glm <- opencltools::load_kernel_library("ex_glmbayes_nmath",
                                              package = "nmathopencl")

# Load with diagnostic output to trace the sort order
nmath_src <- opencltools::load_kernel_library("nmath",
                                              package = "nmathopencl",
                                              verbose = TRUE)

The annotation format

For opencltools::load_kernel_library() to sort correctly, every .cl file in the subdirectory must begin with an annotation block:

// @provides: symbol1, symbol2
// @depends:  fileA, fileB
// @includes: library_name

Rules for @depends:

• List only direct dependencies, not the full transitive set. The resolver computes the transitive closure automatically.
• Every non-header file must list the library header file (the file whose basename matches the subdirectory name) in @depends, so the header is always loaded first.
• If a file has no dependencies at all (i.e., it is the library header), leave @depends empty or omit the tag.

Example for dgamma.cl:

// @provides: dgamma
// @depends:  nmath, dpois, lgamma
// @includes: nmath

This tells the resolver: emit nmath.cl, dpois.cl, and lgamma.cl before dgamma.cl. The resolver handles those files’ own dependencies recursively.

The topological sort algorithm

opencltools::load_kernel_library() uses a straightforward iterative topological sort:

1. Parse all .cl files and extract their @provides and @depends tags.
2. Build a set of “unsorted” files. Initialize the “sorted” set to empty.
3. In each pass, find every unsorted file whose @depends entries are all already in the sorted set. Emit those files and add them to the sorted set.
4. Repeat until all files are sorted or no progress is made.
5. If no progress is made but unsorted files remain, throw: "Dependency sort failed: unresolved dependencies remain."

Files with an empty @depends list are emitted first (pass 1). These are always the library header files.

Pass 1: emitting nmath.cl, Rmath.cl, dpq.cl
Pass 2: emitting chebyshev.cl, cospi.cl, fmax2.cl, gammalims.cl
Pass 3: emitting lgammacor.cl
Pass 4: emitting lgamma.cl, gamma.cl
...

Cycle detection and breaking

If file A lists file B in its @depends and file B lists file A, the resolver will detect this on the first pass where neither can be promoted, and throw an error. If verbose = TRUE, it prints the stuck files before throwing.

The standard fix is to split one of the mutually dependent files into two:

• A “cycle-free” fragment containing functions that make no forward call.
• A “cycle-dependent” fragment containing functions that call the cycle-free fragment.
• A refactored.cl that provides forward declarations for any symbols referenced before they are defined.

Chapter 04 describes the three specific cycles in the nmath library and how they are resolved.

Assembling a complete program

A complete OpenCL program string is assembled by concatenating library and kernel sources in order:

library(nmathopencl)

# 1. Load the nmath library (sorted automatically)
nmath_src  <- opencltools::load_kernel_library("nmath", package = "nmathopencl")

# 2. Load the kernel entry-point
kernel_src <- opencltools::load_kernel_source("src/dnorm_kernel.cl",
                                              package = "nmathopencl")

# 3. Concatenate into a single program string
program    <- paste(nmath_src, kernel_src, sep = "\n")

This program string is then passed to the C++ runner (see Chapter 09).

Using libraries from another package

The package argument tells opencltools::load_kernel_source() and opencltools::load_kernel_library() which package’s inst/cl/ to look in:

# Load the curated nmath subset shipped inside nmathopencl
# for use by a downstream package's kernels
nmath_sub <- opencltools::load_kernel_library("ex_glmbayes_nmath",
                                  package = "nmathopencl")

# Load a custom kernel from the same downstream package
my_kernel <- opencltools::load_kernel_source("ex_glmbayes_src/f2_f3_binomial_logit.cl",
                                 package = "nmathopencl")

program <- paste(nmath_sub, my_kernel, sep = "\n")

This is exactly the pattern used by f2_f3_opencl() in the ex_glmbayes example (see Chapter 10).

Dependency index — faster, kernel-specific loading

opencltools::load_kernel_library() always sorts and loads all files in the subdirectory. For a large library like nmath (137 files) this is thorough but wasteful when only a small subset is needed for a specific kernel.

nmathopencl therefore ships a pre-built dependency index alongside every curated library subdirectory. The index encodes the full transitive dependency map and the global load order, enabling two important optimizations:

1. load_library_for_kernel() (R) — loads only the files required by one specific kernel, with no sort at runtime.
2. load_library_for_kernel() (C++) — the same function implemented entirely in C++, suitable for use inside Rcpp kernel wrappers.

write_kernel_dependency_index(library_dir, verbose = TRUE)

stem    all_depends
refactored  
Rmath   refactored
nmath   refactored, Rmath
chebyshev   refactored, Rmath, nmath
dbinom  dpq, refactored, Rmath, nmath, stirlerr_cycle_free, ...

# Regenerate after changing the nmath library
nmath_dir <- system.file("cl", "nmath", package = "nmathopencl")
write_kernel_dependency_index(nmath_dir, verbose = TRUE)

load_library_for_kernel(kernel_path, library_dir,
                        depends_tag = "all_depends",
                        index = NULL)

nmath_dir <- system.file("cl", "nmath", package = "nmathopencl")

# Load the index once
idx <- readRDS(file.path(nmath_dir, "kernel_dependency_index.rds"))

# Re-use across multiple kernels --- only the subset for each kernel is read
src_gaussian <- load_library_for_kernel(
    kernel_path = system.file("cl", "ex_glmbayes_src",
                              "f2_f3_gaussian.cl", package = "nmathopencl"),
    library_dir = nmath_dir,
    depends_tag = "depends_nmath",
    index       = idx
)
src_gamma <- load_library_for_kernel(
    kernel_path = system.file("cl", "ex_glmbayes_src",
                              "f2_f3_gamma.cl", package = "nmathopencl"),
    library_dir = nmath_dir,
    depends_tag = "depends_nmath",
    index       = idx
)

// @depends_nmath: dbinom, pnorm, dnorm

extract_library_subset(kernel_paths, library_dir, dest_dir,
                       depends_tag = "all_depends",
                       index = NULL,
                       overwrite = FALSE)

nmath_dir    <- system.file("cl", "nmath",           package = "nmathopencl")
src_dir      <- system.file("cl", "ex_glmbayes_src", package = "nmathopencl")
dest_dir     <- "inst/cl/mypkg_nmath"   # must exist

idx <- readRDS(file.path(nmath_dir, "kernel_dependency_index.rds"))

result <- extract_library_subset(
    kernel_paths = list.files(src_dir, pattern = "\\.cl$", full.names = TRUE),
    library_dir  = nmath_dir,
    dest_dir     = dest_dir,
    depends_tag  = "depends_nmath",
    index        = idx
)
print(result)  # data frame: stem, source, dest, copied

#include "openclPort.h"   // declares load_library_for_kernel

// Inside a kernel wrapper, after the family/link dispatch has set kernel_file:
std::string nmath_source = openclPort::load_library_for_kernel(
    kernel_file,          // e.g. "ex_glmbayes_src/f2_f3_binomial_logit.cl"
    "ex_glmbayes_nmath",  // library subdirectory
    "nmathopencl",        // package
    "depends_nmath"       // annotation tag
);

// @depends_nmath: dbinom, pnorm, dnorm

Error messages