rhai/RELEASES.md

Rhai Release Notes

Version 0.14.2

Regression fix

• Do not optimize script with eval_expression - it is assumed to be one-off and short.

Breaking changes

• Engine::compile_XXX functions now return ParseError instead of Box<ParseError>.
• The RegisterDynamicFn trait is merged into the RegisterResutlFn trait which now always returns Result<Dynamic, Box<EvalAltResult>>.
• Default maximum limit on levels of nested function calls is fine-tuned and set to a different value.
• Some operator functions are now built in (see Speed enhancements below), so they are available even under Engine::new_raw.
• Strings are now immutable. The type rhai::ImmutableString is used instead of std::string::String. This is to avoid excessive cloning of strings. All native-Rust functions taking string parameters should switch to rhai::ImmutableString (which is either Rc<String> or Arc<String> depending on whether the sync feature is used).

New features

• Set limit on maximum level of nesting expressions and statements to avoid panics during parsing.
• New EvalPackage to disable eval.
• More benchmarks.

Speed enhancements

• Common operators (e.g. +, >, ==) now call into highly efficient built-in implementations for standard types (i.e. INT, FLOAT, bool, char, () and ImmutableString) if not overridden by a registered function. This yields a 5-10% speed benefit depending on script operator usage. Scripts running tight loops will see significant speed-up.
• Common assignment operators (e.g. +=, %=) now call into highly efficient built-in implementations for standard types (i.e. INT, FLOAT, bool, char, () and ImmutableString) if not overridden by a registered function.
• Implementations of common operators for standard types are removed from the ArithmeticPackage and LogicPackage (and therefore the CorePackage) because they are now always available, even under Engine::new_raw.
• Operator-assignment statements (e.g. +=) are now handled directly and much faster.
• Strings are now immutable and use the rhai::ImmutableString type, eliminating large amounts of cloning.

Version 0.14.1

The major features for this release is modules, script resource limits, and speed improvements (mainly due to avoiding allocations).

New features

• Modules and module resolvers allow loading external scripts under a module namespace. A module can contain constant variables, Rust functions and Rhai functions.
• export variables and private functions.
• Indexers for Rust types.
• Track script evaluation progress and terminate script run.
• Set limit on maximum number of operations allowed per script run.
• Set limit on maximum number of modules loaded per script run.
• A new API, Engine::compile_scripts_with_scope, can compile a list of script segments without needing to first concatenate them together into one large string.
• Stepped range function with a custom step.

Speed improvements

StaticVec

A script contains many lists - statements in a block, arguments to a function call etc. In a typical script, most of these lists tend to be short - e.g. the vast majority of function calls contain fewer than 4 arguments, while most statement blocks have fewer than 4-5 statements, with one or two being the most common. Before, dynamic Vec's are used to hold these short lists for very brief periods of time, causing allocations churn.

In this version, large amounts of allocations are avoided by converting to a StaticVec - a list type based on a static array for a small number of items (currently four) - wherever possible plus other tricks. Most real-life scripts should see material speed increases.

Pre-computed variable lookups

Almost all variable lookups, as well as lookups in loaded modules, are now pre-computed. A variable's name is almost never used to search for the variable in the current scope.

Getters and setter function names are also pre-computed and cached, so no string allocations are performed during a property get/set call.

Pre-computed function call hashes

Lookup of all function calls, including Rust and Rhai ones, are now through pre-computed hashes. The function name is no longer used to search for a function, making function call dispatches much faster.

Large Boxes for expressions and statements

The expression (Expr) and statement (Stmt) types are modified so that all of the variants contain only one single Box to a large allocated structure containing all the fields. This makes the Expr and Stmt types very small (only one single pointer) and improves evaluation speed due to cache efficiency.

Error handling

Previously, when an error occurs inside a function call, the error position reported is the function call site. This makes it difficult to diagnose the actual location of the error within the function.

A new error variant EvalAltResult::ErrorInFunctionCall is added in this version. It wraps the internal error returned by the called function, including the error position within the function.