RuntimeGeneratedFunctions.jl: Generate functions at runtime
RuntimeGeneratedFunctions are functions generated at runtime without world-age issues and with the full performance of a standard Julia anonymous function. This builds functions in a way that avoids eval.
Note that RuntimeGeneratedFunction does not handle closures. Please use the GeneralizedGenerated.jl package for more fixable staged programming. While GeneralizedGenerated.jl is more powerful, RuntimeGeneratedFunctions.jl handles large expressions better.
Tutorials and Documentation
For information on using the package, see the stable documentation. Use the in-development documentation for the version of the documentation, which contains the unreleased features.
Simple Example
Here's an example showing how to construct and immediately call a runtime generated function:
using RuntimeGeneratedFunctions
RuntimeGeneratedFunctions.init(@__MODULE__)
function no_worldage()
ex = :(function f(_du, _u, _p, _t)
@inbounds _du[1] = _u[1]
@inbounds _du[2] = _u[2]
nothing
end)
f1 = @RuntimeGeneratedFunction(ex)
du = rand(2)
u = rand(2)
p = nothing
t = nothing
f1(du, u, p, t)
end
no_worldage()Changing how global symbols are looked up
If you want to use helper functions or global variables from a different module within your function expression, you'll need to pass a context_module to the @RuntimeGeneratedFunction constructor. For example
RuntimeGeneratedFunctions.init(@__MODULE__)
module A
using RuntimeGeneratedFunctions
RuntimeGeneratedFunctions.init(A)
helper_function(x) = x + 1
end
function g()
expression = :(f(x) = helper_function(x))
# context module is `A` so that `helper_function` can be found.
f = @RuntimeGeneratedFunction(A, expression)
@show f(1)
endPrecompilation and setting the function expression cache
For technical reasons, RuntimeGeneratedFunctions needs to cache the function expression in a global variable within some module. This is normally transparent to the user, but if the RuntimeGeneratedFunction is evaluated during module precompilation, the cache module must be explicitly set to the module currently being precompiled. This is relevant for helper functions in some module, which construct a RuntimeGeneratedFunction on behalf of the user. For example, in the following code, any third party user of HelperModule.construct_rgf() user needs to pass their own module as the cache_module if they want the returned function to work after precompilation:
RuntimeGeneratedFunctions.init(@__MODULE__)
# Imagine HelperModule is in a separate package and will be precompiled
# separately.
module HelperModule
using RuntimeGeneratedFunctions
RuntimeGeneratedFunctions.init(HelperModule)
function construct_rgf(cache_module, context_module, ex)
ex = :((x) -> $ex^2 + x)
RuntimeGeneratedFunction(cache_module, context_module, ex)
end
end
function g()
ex = :(x + 1)
# Here cache_module is set to the module currently being compiled so that
# the returned RGF works with Julia's module precompilation system.
HelperModule.construct_rgf(@__MODULE__, @__MODULE__, ex)
end
f = g()
@show f(1)Retrieving Expressions
From a constructed RuntimeGeneratedFunction, you can retrieve the expressions using the RuntimeGeneratedFunctions.get_expression command. For example:
ex = :((x) -> x^2)
rgf = @RuntimeGeneratedFunction(ex)
julia> RuntimeGeneratedFunctions.get_expression(rgf)
:((x,)->begin
#= REPL[14]:1 =#
x ^ 2
end)This can be used to get the expression even if drop_expr has been performed.
Example: Retrieving Expressions from ModelingToolkit.jl
ModelingToolkit.jl uses RuntimeGeneratedFunctions.jl for the construction of its functions to avoid issues of world-age. Take for example its tutorial:
using ModelingToolkit, RuntimeGeneratedFunctions
using ModelingToolkit: t_nounits as t, D_nounits as D
@mtkmodel FOL begin
@parameters begin
τ # parameters
end
@variables begin
x(t) # dependent variables
end
@equations begin
D(x) ~ (1 - x) / τ
end
end
using DifferentialEquations: solve
@mtkbuild fol = FOL()
prob = ODEProblem(fol, [fol.x => 0.0], (0.0, 10.0), [fol.τ => 3.0])If we check the function:
julia> prob.f
(::ODEFunction{true, SciMLBase.AutoSpecialize, ModelingToolkit.var"#f#697"{RuntimeGeneratedFunction{(:ˍ₋arg1, :ˍ₋arg2, :t), ModelingToolkit.var"#_RGF_ModTag", ModelingToolkit.var"#_RGF_ModTag", (0x2cce5cf2, 0xd20b0d73, 0xd14ed8a6, 0xa4d56c4f, 0x72958ea1), Nothing}, RuntimeGeneratedFunction{(:ˍ₋out, :ˍ₋arg1, :ˍ₋arg2, :t), ModelingToolkit.var"#_RGF_ModTag", ModelingToolkit.var"#_RGF_ModTag", (0x7f3c227e, 0x8f116bb1, 0xb3528ad5, 0x9c57c605, 0x60f580c3), Nothing}}, UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, ModelingToolkit.var"#852#generated_observed#706"{Bool, ODESystem, Dict{Any, Any}, Vector{Any}}, Nothing, ODESystem, Nothing, Nothing}) (generic function with 1 method)It's a RuntimeGeneratedFunction. We can find the code for this system using the retrieval command on the function we want. For example, for the in-place function:
julia> RuntimeGeneratedFunctions.get_expression(prob.f.f.f_iip)
:((ˍ₋out, ˍ₋arg1, ˍ₋arg2, t)->begin
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:373 =#
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:374 =#
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:375 =#
begin
begin
begin
#= C:\Users\accou\.julia\packages\Symbolics\HIg7O\src\build_function.jl:546 =#
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:422 =# @inbounds begin
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:418 =#
ˍ₋out[1] = (/)((+)(1, (*)(-1, ˍ₋arg1[1])), ˍ₋arg2[1])
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:420 =#
nothing
end
end
end
end
end)or the out-of-place function:
julia> RuntimeGeneratedFunctions.get_expression(prob.f.f.f_oop)
:((ˍ₋arg1, ˍ₋arg2, t)->begin
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:373 =#
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:374 =#
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:375 =#
begin
begin
begin
#= C:\Users\accou\.julia\packages\SymbolicUtils\c0xQb\src\code.jl:468 =#
(SymbolicUtils.Code.create_array)(typeof(ˍ₋arg1), nothing, Val{1}(), Val{(1,)}(), (/)((+)(1, (*)(-1, ˍ₋arg1[1])), ˍ₋arg2[1]))
end
end
end
end)Reproducibility
The documentation of this SciML package was built using these direct dependencies,
Status `~/work/RuntimeGeneratedFunctions.jl/RuntimeGeneratedFunctions.jl/docs/Project.toml`
[e30172f5] Documenter v1.13.0
[7e49a35a] RuntimeGeneratedFunctions v0.5.15 `~/work/RuntimeGeneratedFunctions.jl/RuntimeGeneratedFunctions.jl`and using this machine and Julia version.
Julia Version 1.11.5
Commit 760b2e5b739 (2025-04-14 06:53 UTC)
Build Info:
Official https://julialang.org/ release
Platform Info:
OS: Linux (x86_64-linux-gnu)
CPU: 4 × AMD EPYC 7763 64-Core Processor
WORD_SIZE: 64
LLVM: libLLVM-16.0.6 (ORCJIT, znver3)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)A more complete overview of all dependencies and their versions is also provided.
Status `~/work/RuntimeGeneratedFunctions.jl/RuntimeGeneratedFunctions.jl/docs/Manifest.toml`
[a4c015fc] ANSIColoredPrinters v0.0.1
[1520ce14] AbstractTrees v0.4.5
[944b1d66] CodecZlib v0.7.8
[ffbed154] DocStringExtensions v0.9.5
[e30172f5] Documenter v1.13.0
[e2ba6199] ExprTools v0.1.10
[d7ba0133] Git v1.4.0
[b5f81e59] IOCapture v0.2.5
[692b3bcd] JLLWrappers v1.7.0
[682c06a0] JSON v0.21.4
[0e77f7df] LazilyInitializedFields v1.3.0
[d0879d2d] MarkdownAST v0.1.2
[69de0a69] Parsers v2.8.3
⌅ [aea7be01] PrecompileTools v1.2.1
[21216c6a] Preferences v1.4.3
[2792f1a3] RegistryInstances v0.1.0
[7e49a35a] RuntimeGeneratedFunctions v0.5.15 `~/work/RuntimeGeneratedFunctions.jl/RuntimeGeneratedFunctions.jl`
[3bb67fe8] TranscodingStreams v0.11.3
[2e619515] Expat_jll v2.6.5+0
[f8c6e375] Git_jll v2.49.0+0
[94ce4f54] Libiconv_jll v1.18.0+0
[9bd350c2] OpenSSH_jll v10.0.1+0
[458c3c95] OpenSSL_jll v3.5.0+0
[0dad84c5] ArgTools v1.1.2
[56f22d72] Artifacts v1.11.0
[2a0f44e3] Base64 v1.11.0
[ade2ca70] Dates v1.11.0
[f43a241f] Downloads v1.6.0
[7b1f6079] FileWatching v1.11.0
[b77e0a4c] InteractiveUtils v1.11.0
[b27032c2] LibCURL v0.6.4
[76f85450] LibGit2 v1.11.0
[8f399da3] Libdl v1.11.0
[56ddb016] Logging v1.11.0
[d6f4376e] Markdown v1.11.0
[a63ad114] Mmap v1.11.0
[ca575930] NetworkOptions v1.2.0
[44cfe95a] Pkg v1.11.0
[de0858da] Printf v1.11.0
[3fa0cd96] REPL v1.11.0
[9a3f8284] Random v1.11.0
[ea8e919c] SHA v0.7.0
[9e88b42a] Serialization v1.11.0
[6462fe0b] Sockets v1.11.0
[f489334b] StyledStrings v1.11.0
[fa267f1f] TOML v1.0.3
[a4e569a6] Tar v1.10.0
[8dfed614] Test v1.11.0
[cf7118a7] UUIDs v1.11.0
[4ec0a83e] Unicode v1.11.0
[deac9b47] LibCURL_jll v8.6.0+0
[e37daf67] LibGit2_jll v1.7.2+0
[29816b5a] LibSSH2_jll v1.11.0+1
[c8ffd9c3] MbedTLS_jll v2.28.6+0
[14a3606d] MozillaCACerts_jll v2023.12.12
[efcefdf7] PCRE2_jll v10.42.0+1
[83775a58] Zlib_jll v1.2.13+1
[8e850ede] nghttp2_jll v1.59.0+0
[3f19e933] p7zip_jll v17.4.0+2
Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`You can also download the manifest file and the project file.