Hint class base

Represents the outcome of a runtime hint operation within the Jetleaf execution pipeline.

A Hint acts as a lightweight, immutable container that encodes:

  • Whether a hint execution path actually ran
  • The result of that execution, if any

This is used extensively throughout the AOT/JIT hybrid runtime to determine whether a hint-provided override, transformation, or precomputation should replace or bypass the default execution flow.

Purpose

Many components in Jetleaf—such as RuntimeHint, RuntimeHintProcessor, and the generative AOT executor—need a uniform way to express:

  • “I executed and produced a replacement value”
  • “I executed but intentionally produced no result”
  • “I did not execute; please fall back to normal logic”

Hint encodes these states concisely without requiring exception-based or sentinel-value signaling.

Execution States

A Hint can be in one of three canonical states:

State Meaning Created by
Executed with result The hint ran and produced a value Hint.executed
Executed without result The hint ran but intentionally returned no meaningful value Hint.executedWithoutResult
Not executed The hint declined to participate; downstream systems must fall back Hint.notExecuted

These states are used by the runtime to coordinate layered hint chains—where multiple hint processors may try to contribute logic.

Immutability

All fields are final, making every Hint instance effectively a sealed, single-purpose message that cannot be modified after creation.

Typical Usage

final hint = processor.invokeMethod()(instance, 'run', [], {});

if (hint.getIsExecuted()) {
  final value = hint.getResult();
  // Use the hint result instead of invoking reflectively.
} else {
  // Fallback to default execution.
}

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

getIsExecuted() → bool
Indicates whether the hint logic actually executed.
getResult() → Object?
Returns the result value produced by the hint, if any.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

executed(Object object) → Hint
Creates a Hint representing an executed operation that produced a result.
executedWithoutResult() → Hint
Creates a Hint representing an executed operation that intentionally produced no result.
notExecuted() → Hint
Creates a Hint representing a hint that did not execute.