Caching recursive functions

@cache [options...] function foo(arg1::Type, arg2::Type; kwargs...)::ReturnType
    # ...
end

Create a cached version of the function foo. This is typically useful for recursive functions that descend through an expression tree.

The return type of the function should be annotated to avoid warnings. If any of the argument types is a BasicSymbolic, uses a special caching for efficiency. If an argument has Any type or a Union containing BasicSymbolic, a runtime check is performed to handle it. This can be avoided if the type is annotated with BasicSymbolic. The maximum number of entries in the cache can be set using the limit option by providing an integer size. This defaults to 100_000. When this limit is hit, a fraction of the entries in the cache will be cleared at random. The fraction of entries retained is given by the retain_fraction option, which defaults to 0.5.

Multiple methods of the same function cannot be cached and will lead to an error. This should be avoided by creating a wrapper function which calls the one with ,multiple methods, and caching the wrapper. The function with multiple methods should recursively call the wrapper. Caching a single method is valid.

The cache is thread-safe and uses TaskLocalValues.jl to maintain a task-specific cache.

The caching behavior for this function is enabled by default. Use the enabled option to toggle this.

See also: SymbolicUtils.get_limit, SymbolicUtils.set_limit!, SymbolicUtils.get_retain_fraction, SymbolicUtils.set_retain_fraction!, SymbolicUtils.toggle_caching!, SymbolicUtils.is_caching_enabled, SymbolicUtils.get_stats, SymbolicUtils.clear_cache!, [SymbolicUtils.reset_stats!].

associated_cache(fn)

Given a function annotated with @cache, get the cache struct it uses. Automatically implemented by @cache.

get_limit(fn) -> Any

Get the maximum size for the cache associated with function fn.

is_caching_enabled(fn) -> Any

Check whether caching is enabled for fn.