API

@fusible <method definition>

Generates two new method definitions, evaluating them along with the original. One definition replaces all arguments that have @fuse annotations with FusibleBroadcastAccumulators, while the other definition replaces them with UnfusibleBroadcastEvaluators. If an annotated argument in the original definition is restricted to some type T, the new methods are restricted to FusibleBroadcastAccumulator{T} and UnfusibleBroadcastEvaluator{T}.

This macro can be thought of as an analogue of @simd that operates at the level of broadcast expressions. Using this macro amounts to telling the compiler that the body of the method definition satisfies the following constraints:

• all broadcasts are in-place
• all broadcast destinations are either an arguments annotated with @fuse or components of annotated arguments, and they are not aliased by other names
• all broadcasts can be freely rearranged, regardless of any changes to floating point round-off error this may cause
• all non-broadcast operations on arguments annotated with @fuse will always yield the same results when evaluated on inputs with some particular types

The first two constraints are checked automatically, but users should ensure that they satisfy the other constraints when marking a method as @fusible.

@lazy_dot <expression>

Roughly equivalent to @., but without the call to Base.materialize that gets inserted during the code lowering process.

Returns a FusibleBroadcasted object that lazily represents the computations in the given expression. This object can be inserted directly into other broadcast expressions, providing a mechanism for splitting up complex broadcasts into smaller broadcasts without triggering allocations. Passing this object to Base.materialize should be equivalent to replacing @lazy_dot with @..

DroppedBroadcast()

Used as a replacement for in-place broadcast expressions that get dropped from method definitions by @fusible. Also functions as an intermediate value during broadcast simplification.

FusedBroadcast(accumulator, optimizer)

A materializable form of the lazy broadcast expressions in the given FusibleBroadcastAccumulator, divided into FusedBroadcastSteps based on the given FusibleBroadcastOptimizer.

FusedBroadcastStep(names, values)

A set of values, some of which may be FusibleBroadcasted objects, that can be simultaneously materialized into a destination at the given FieldNames.

FusibleBroadcastAccumulator([dest], [warn_on_unwrap])

A wrapper for dest that can be used to lazily store broadcast expressions which appear in functions that are annotated with @fusible.

FusibleBroadcastOptimizer

Controls how a FusibleBroadcastAccumulator gets divided into FusedBroadcastSteps within a FusedBroadcast. This can be based on memory usage, register pressure, code generation time, or some combination of factors.

FusibleBroadcasted(f, args)

An analogue of Base.broadcasted that avoids computing broadcast styles and axes, but which gets converted into the result of Base.broadcasted when used in a broadcast expression.

LazyOrEagerWrapper

Supertype of UnfusibleBroadcastEvaluators and FusibleBroadcastAccumulators, both of which are constructed as <Type>([dest], [warn_on_unwrap]).

The first constructor argument, dest, which is set to UnknownDestination by default, represents a destination into which broadcasts can be materialized. This argument only needs to be specified if the wrapper is going to be passed to unwrap, in which case the default value of UnknownDestination will cause an error to be thrown. For an UnfusibleBroadcastEvaluator, dest should be the destination itself, but, for a FusibleBroadcastAccumulator, it only has to be similar to the final FusedBroadcast destination.

The second constructor argument, warn_on_unwrap, which is set to false by default, toggles whether a warning will be logged when the wrapper is passed to unwrap (except for when this occurs in one of several common functions like propertynames and eltype, which are easily extended to LazyOrEagerWrappers with well-defined destinations). This argument only needs to be specified when dest is specified, since an UnknownDestination will always cause unwrap to throw an error. A LazyOrEagerWrapper gets unwrapped whenever it is passed from a user-defined method annotated with @fusible to one that is not annotated, so this toggle can be used to check whether all of the broadcasts executed by a block of code appear within annotated methods and can be handled by a FusibleBroadcastAccumulator, or if some need to be handled separately by an UnfusibleBroadcastEvaluator.

MaximizeFusion()

The default FusibleBroadcastOptimizer. Evaluates all accumulated broadcasts in a single step.

UnfusibleBroadcastEvaluator([dest], [warn_on_unwrap])

A wrapper for dest that can be used to eagerly evaluate broadcast expressions which appear in functions that are not annotated with @fusible.

UnknownDestination()

The default destination for a LazyOrEagerWrapper. Errors upon being unwrapped.

fused_materialize!(accumulator, name, value, [f])

Adds an instruction of the form dest.name .= value (or dest.name .f= value if a reduction operator f is specified) to a FusibleBroadcastAccumulator.

needs_unwrap_before_call(f, args...)

When one or more arguments in args are LazyOrEagerWrappers, this checks whether unwrap needs to be called on them before f(args...) is evaluated. If at least one of the arguments also has warn_on_unwrap set to true, a warning will be logged whenever unwrap is called.

In order to disable the warning for a particular function f (regardless of whether it has any arguments with warn_on_unwrap set to true), add a new method for f that accepts LazyOrEagerWrappers and calls unwrap on them, and then extend needs_unwrap_before_call to return false for that method.

simplified_fusible_broadcasted(value)

When value is a FusibleBroadcasted, this fuses all nested functions and all linear combinations of linear functions within value.

simplify_accumulated_broadcasts!(accumulator)

Rearranges the broadcast expressions in a FusibleBroadcastAccumulator so as to minimize the number of operations required to materialize them.

unwrap(wrapper)

Extracts the destination of a LazyOrEagerWrapper; i.e., the array or array-like object into which broadcasts get materialized. Throws an error when the destination is an UnknownDestination.

warn_on_unwrap(wrapper)

Checks whether a warning should be logged when a LazyOrEagerWrapper is passed to unwrap.