Lazy Evaluation
By default, allrequired
and optional
inputs are evaluated before a node can be run. Sometimes, however, an
input won’t necessarily be used and evaluating it would result in unnecessary processing. Here are some examples
of nodes where lazy evaluation may be beneficial:
- A
ModelMergeSimple
node where the ratio is either0.0
(in which case the first model doesn’t need to be loaded) or1.0
(in which case the second model doesn’t need to be loaded). - Interpolation between two images where the ratio (or mask) is either entirely
0.0
or entirely1.0
. - A Switch node where one input determines which of the other inputs will be passed through.
There is very little cost in making an input lazy. If it’s something you can do, you generally should.
Creating Lazy Inputs
There are two steps to making an input a “lazy” input. They are:- Mark the input as lazy in the dictionary returned by
INPUT_TYPES
- Define a method named
check_lazy_status
(note: not a class method) that will be called prior to evaluation to determine if any more inputs are necessary.
0.0
, we don’t need to evaluate any part of the tree leading up to the second image. If the entire mask is 1.0
, we can skip evaluating the first image.
Defining INPUT_TYPES
Declaring that an input is lazy is as simple as adding a lazy: True
key-value pair to the input’s options dictionary.
image1
and image2
are both marked as lazy inputs, but mask
will always be evaluated.
Defining check_lazy_status
A check_lazy_status
method is called if there are one or more lazy inputs that are not yet available. This method receives the same arguments as the standard execution function. All available inputs are passed in with their final values while unavailable lazy inputs have a value of None
.
The responsibility of the check_lazy_status
function is to return a list of the names of any lazy inputs that are needed to proceed. If all lazy inputs are available, the function should return an empty list.
Note that check_lazy_status
may be called multiple times. (For example, you might find after evaluating one lazy input that you need to evaluate another.)
Note that because the function uses actual input values, it is not a class method.
Full Example
Execution Blocking
While Lazy Evaluation is the recommended way to “disable” part of a graph, there are times when you want to disable anOUTPUT
node that doesn’t implement lazy evaluation itself. If it’s an output node that you developed yourself, you should just add lazy evaluation as follows:
- Add a required (if this is a new node) or optional (if you care about backward compatibility) input for
enabled
that defaults toTrue
- Make all other inputs
lazy
inputs - Only evaluate the other inputs if
enabled
isTrue
comfy_execution.graph.ExecutionBlocker
. This special object can be returned as an output from any socket. Any nodes which receive an ExecutionBlocker
as input will skip execution and return that ExecutionBlocker
for any outputs.
There is intentionally no way to stop an ExecutionBlocker from propagating forward. If you think you want this, you should really be using Lazy Evaluation.
Usage
There are two ways to construct and use anExecutionBlocker
- Pass
None
into the constructor to silently block execution. This is useful for cases where blocking execution is part of a successful run — like disabling an output.
- Pass a string into the constructor to display an error message when a node is blocked due to receiving the object. This can be useful if you want to display a meaningful error message if someone uses a meaningless output — for example, the
VAE
output when loading a model that doesn’t contain VAEs.