Runtime Dispatch

StringZilla detects the running CPU’s SIMD features and routes every kernel to the fastest capability both the CPU and this build have, without recompilation. Capabilities are sz.Capability flags, one member per CPU capability, like sz.Capability.HASWELL or sz.Capability.NEON; GPU bits sit above every member, so a GPU mask prints as a number.

The producers report capabilities for the CPU, or for one GPU by its runtime’s ordinal, or make a stream on that GPU, and are the only calls taking an ordinal.

• sz.__version__ — the package version string.
• sz.cpu_capabilities_detected(), sz.cuda_capabilities_detected(ordinal) — what the device can execute, whether or not its kernels were compiled in.
• sz.cpu_capabilities_compiled(), sz.cuda_capabilities_compiled() — what this build holds kernels for, whether or not the device runs them.
• sz.cpu_capabilities_enabled(), sz.cuda_capabilities_enabled(ordinal) — what calls dispatch with, both of the above; on the CPU it always has SERIAL.
• sz.cuda_count_devices() — the number of CUDA devices; it raises RuntimeError when none answers, as when this build lacks its kernels, and so does an ordinal past the last device.
• sz.cpu_configure_thread(capabilities) — prepare the calling thread for the kernels of capabilities; call it on every thread that runs kernels.
• sz.cuda_stream_init(ordinal), sz.cuda_stream_free(stream) — make a stream on one device, as the integer every stream= takes, and free it once nothing queued on it remains.
• sz.synchronize(capabilities, stream=None) — wait for one stream of the vendor capabilities names, or its default one.

ROCm and Metal have the same rocm_ and metal_ producers. Every function that runs kernels also takes a keyword-only capabilities=, narrowing that one call and leaving every other call alone. The keyword keeps no serial fallback, so a mask with no kernel for the call raises LookupError.

import stringzilla as sz

sz.cpu_capabilities_enabled()                                 # e.g. <Capability.SERIAL|NEON|NEONAES|NEONSHA: 449>
sz.find("haystack", "st", capabilities=sz.Capability.SERIAL)  # one call on the scalar kernel
sz.cpu_configure_thread(sz.cpu_capabilities_enabled())        # on a thread that runs kernels
[sz.cuda_capabilities_enabled(ordinal) for ordinal in range(sz.cuda_count_devices())]  # raises without CUDA

Engines and the stateful objects, like Hasher, Sha256 and the AES keys, dispatch every call with the capabilities they were constructed with.