numba_vulkan.kernelcache#

On-disk cache of compiled kernels.

Turning a kernel’s LLVM IR into SPIR-V (linking libclc, optimising, restructuring, running the backend) is the larger part of compiling it. The result depends only on the IR that Numba’s lowering produces and on this package, so it is stored under a hash of both and reused by later processes. Numba’s own pipeline still runs every time, which is what makes the cache safe: a change to a kernel, to a function it calls or to a global it reads changes the IR and therefore the hash.

Entries live in kernels/ below numba_vulkan.libclc.cache_directory and can be deleted at any time. Setting NUMBA_VULKAN_CACHE=0 turns the cache off.

Kernels compiled with @nv.jit(cache=True) are stored whole as well, in functions/, which skips Numba’s pipeline too. They are found by their bytecode, the timestamps of their source files and those of the @nv.jit functions they call, as with Numba’s cache=True; see numba_vulkan.dispatcher.VulkanDispatcher.compile.

Attributes#

ENV_VAR

Functions#

enabled()

Whether kernels are cached on disk.

fingerprint()

Hash of everything besides a kernel's IR that shapes its SPIR-V.

normalise(source)

Remove what differs between processes from unoptimised LLVM IR.

key(source, *settings)

Name of the cache entry for a kernel.

load(name)

Read an entry.

store(name, entry)

Write an entry; failures to write are ignored.

source_stamp(function)

What identifies a Python function's code across processes.

kernel_key(stamps, *settings)

Name of the cache entry for a compiled kernel.

load_kernel(name)

Read a cached kernel.

store_kernel(name, entry)

Write a cached kernel; failures to write are ignored.

Module Contents#

numba_vulkan.kernelcache.ENV_VAR = 'NUMBA_VULKAN_CACHE'#
numba_vulkan.kernelcache.enabled()#

Whether kernels are cached on disk.

Return type:

bool

numba_vulkan.kernelcache.fingerprint()#

Hash of everything besides a kernel’s IR that shapes its SPIR-V.

That is the source of this package, the version of llvmlite (and with it of LLVM), the libclc file in use, and the llc program if one replaces llvmlite’s backend.

Return type:

str

numba_vulkan.kernelcache.normalise(source)#

Remove what differs between processes from unoptimised LLVM IR.

Parameters:

source (str) – The IR of all modules of a kernel.

Returns:

The IR with Numba’s per-process function counters renumbered in order of appearance and module names removed.

Return type:

str

numba_vulkan.kernelcache.key(source, *settings)#

Name of the cache entry for a kernel.

Parameters:

  • source (str) – Unoptimised LLVM IR of all modules of the kernel, after normalise and with constant arrays numbered canonically.

  • *settings – Everything else that affects code generation, such as the narrowing mode.

Returns:

A hexadecimal digest.

Return type:

str

numba_vulkan.kernelcache.load(name)#

Read an entry.

Parameters:

name (str) – Name of the entry, from key.

Returns:

The entry as passed to store, or None if there is none or it is damaged.

Return type:

dict or None

numba_vulkan.kernelcache.store(name, entry)#

Write an entry; failures to write are ignored.

Parameters:

  • name (str) – Name of the entry, from key.

  • entry (dict) – spirv (bytes), llvm_ir (str) and any JSON-serialisable metadata.

numba_vulkan.kernelcache.source_stamp(function)#

What identifies a Python function’s code across processes.

Parameters:

function (function) – A Python function.

Returns:

Its bytecode with the name, size and modification time of its source file, or None if it has no source file (it was defined interactively or with exec), and cannot be cached.

Return type:

bytes or None

numba_vulkan.kernelcache.kernel_key(stamps, *settings)#

Name of the cache entry for a compiled kernel.

Parameters:

  • stamps (list of bytes) – source_stamp of the kernel and of every function it calls.

  • *settings – Argument types, grid, narrowing mode and options.

Returns:

A hexadecimal digest.

Return type:

str

numba_vulkan.kernelcache.load_kernel(name)#

Read a cached kernel.

Returns:

As passed to store_kernel, or None if there is none or it cannot be read.

Return type:

dict or None

numba_vulkan.kernelcache.store_kernel(name, entry)#

Write a cached kernel; failures to write are ignored.

Parameters:

  • name (str) – From kernel_key.

  • entry (dict) – The compiled kernel and what it needs from the compiling process.