MilesCranmer / DispatchDoctor.jl

DispatchDoctor 🩺 *The doctor's orders: no type instability allowed!* 💊 Usage This package provides the macro to enforce that functions have type stable return values. Calling this function will throw an error for any type instability: Code which is type stable should safely compile away the check: with : Meaning there is zero overhead on this type stability check. (This may not always be true, so be sure to try the workflow in usage in packages) You can use on blocks of code, including blocks, , and anonymous functions. The inverse of is which turns it off: All methods in the block will be wrapped with the type stability check: (*Tip: you cannot import or define macros within a block, unless it is at the "top level" of a submodule. So, if you are wrapping the contents of a package, you should either import any macros outside of , or put them into a submodule.*) (*Tip 2: in the REPL, you must wrap modules with , because the REPL has special handling of the keyword.*) You can disable stability errors for a single scope with the context: although this will error if you try to use it simultaneously from two separate threads. 🧪 Options You can provide the following options to : • : • Change the default mode from to to only emit a warning, or to disable type instability checks by default. • To locally or globally override the mode for a package that uses DispatchDoctor, you can use the key in your LocalPreferences.toml (typically configured with Preferences.jl). • : • Set the code generation level to to only generate a single function body for each stabilized function. The default, , generates an entire duplicate function so that can be used. • To locally or globally override the code generation level for a package that uses DispatchDoctor, you can use the key in your LocalPreferences.toml. • : • Sets the maximum elements in a union to be considered stable. The default is , meaning that all unions are considered unstable. A value of would indicate that is considered stable, but is not. • To locally or globally override the union limit for a package that uses DispatchDoctor, you can use the key in your LocalPreferences.toml. Each of these is denoted a because you may set them globally or at a per-package level with (see below). 🚑 Usage in packages You might find it useful to *only* enable during unit-testing, to have it check every function in a library, but not throw errors for downstream users. You may also want to have warnings instead of errors. For this, use the keyword to set the default behavior: as the mode will turn into a *no-op*, so that DispatchDoctor has no effect on your code by default. If you prefer annotating individual functions but want to avoid repeating keywords (e.g., always using ), you can define a small wrapper macro inside your package: Then you can use throughout your code, while still being able to refer to the original macro explicitly as . The mode is configurable via Preferences.jl, meaning that, within your , you could add a line **before importing your package**: You can also set to be if you would just like warnings. You might also find it useful to set the parameter to instead of the default . This will result in no code duplication, improving precompilation time (although and error messages will be less useful). As with the , you can configure the codegen level with Preferences.jl by using the key. Note that for code coverage to work as expected over stabilized code, you will also need to use . 🔬 Special Cases > [!NOTE] > There are several scenarios and special cases for which type instabilities will be ignored. These are discussed below. • **During precompilation.** • **In unsupported Julia versions** (currently only 1.10.0, 1.13.0) are active) • **When loading code changes with Revise.jl\*.** • \*Basically, will attempt to travel through any 's. However, if you edit the included file and load the changes with Revise.jl, instability checks will get stripped (see [Revise#634). The result will be that the will be ignored. • **Within certain code blocks and function types:** • Within an block • Within a block • Within any function containing a macro • Within a block • Within a block • Within an incompatible macro, such as • - • - Or anything else registered as incompatible with • Parameterized functions like • Functions with an expression-based name like • A function inside another function (a closure). • But note the outer function will still be stabilized. So, e.g., would stabilize , but not . Though if were unstable, would likely be as well, and it would get caught! Note that you can safely use over all of these cases, and special cases will automatically be skipped. Although, if you use internally in some of these cases, like calling within a function on a closure, such as directly on the , then it can still apply. 🩹 Eliminating Type Instabilities Say that you start using and you run into a type instability error. What then? How should you fix it? The first thing you can try is using on the function in question, which will highlight each individual variable's type with a special color for any instabilities. Note that some of the lines you will see are from DispatchDoctor's inserted code. If those are bothersome, you can disable the checking with followed by restarting Julia. Other, much more powerful options to try include Cthulhu.jl and JET.jl, which can provide more detailed type instability reports in an easier-to-read format than . Both packages can also descend into your function calls to help you locate the source of the instability. 🦠 Caveats • Using is likely to increase precompilation time. (To reduce this effect, try the above) • Using over an entire package may result in flagging type instabilities on small functions that act as aliases and may otherwise be inlined by the Julia compiler. Try putting on any suspected such functions if needed. 🧑‍⚕️ Credits Many thanks to @chriselrod and @thofma for tip…