jit_blocks

JitBlocks is a C library built on the top of libgccjit that provides common building blocks for JIT-powered code.

This overview page is best viewed from the rendered Doxygen page.

API Overview

At a high level, there are two types of API interfaces:

• Easy APIs. These APIs create a new compilation context using jit_blocks_get_easy_context_builder, builds a function in it, frees the compilation context, and return the gcc_jit_result and function pointer to end users. It's user's responsibility to call gcc_jit_result_release on the returned gcc_jit_result. Users could replace the default context builder with jit_blocks_set_easy_context_builder. Example:

gcc_jit_result* result = NULL;
jit_blocks_divide_by_k_int_t divide_by_42 =
    jit_blocks_build_divide_by_k_int(42, &result);
assert(divide_by_42 != NULL);
assert(divide_by_42(100) == 2);
gcc_jit_result_release(result);

• Low-level APIs. These APIs are suffixed with _aux and accept an additional gcc_jit_context* custom_ctx parameter. It does not free the passed-in custom_ctx. Users should free both custom_ctx and result at the end of call, as custom_ctx's state is unspecified after call and should not be reused. Example:

gcc_jit_result* result = NULL;
gcc_jit_context* ctx = gcc_jit_context_acquire();
// set arbitrary option for this ctx
jit_blocks_divide_by_k_int_t divide_by_42 =
    jit_blocks_build_divide_by_k_int_aux(42, ctx, &result);
assert(divide_by_42 != NULL);
assert(divide_by_42(100) == 2);
gcc_jit_result_release(result);
gcc_jit_context_release(ctx);

Easy context builder API

See Context Builder utilities for easy APIs

divide-by API builder

Builds divide_by_constant functions. These division functions are often faster than writing runtime_var / runtime_var expressions, as compiler could utilize the known divisor and convert the division into multiplications. Provides similar speedup to libdivide.

See divide-by API builders.

Function Calls builder

Builds a function that calls all specified function pointers in order. Compared to calling function vectors at runtime, it's more branch-predictor-friendly and allows more speculative execution.

See Build a series of function calls

Expression Engine

Builds a stack-based arithmetic expression interpreter.

See Efficient floating point arithmetic expression engine

Dynamic Switch builder

Builds a dynamic switch (val) { case A: ... } block. Useful when the dispatch table is only known at runtime.

See Dynamic Switch Builder

Using this library

For CMake users, the recommended way is to add this project either as a git submodule, or download via FetchContent or CPM.cmake, and then add these lines to your CMakeLists.txt:

add_subdirectory("jit_blocks_dir")
target_link_libraries(YOUR_LIB PRIVATE jit_blocks::jit_blocks)

It should automatically take care of all include directories and linking flags.

Alternatively, you can also write Shell scripts following BUILDING instructions, install them into a local directory, and then manually include the generated headers and built library.

Building and installing

See the BUILDING document.

Contributing

See the CONTRIBUTING document.

Licensing

Apache v2