D4 class

D4 - Static helper class for D4rt bridge code generation.

All generated bridge code uses these static methods for:

  • Type coercion (List/Map from D4rt runtime)
  • Argument extraction (positional and named)
  • Target validation (instance methods)
  • Argument count validation

Example usage in generated bridge code:

// Validate target for instance method
final t = D4.validateTarget<MyClass>(target, 'MyClass');

// Extract required positional argument
final name = D4.getRequiredArg<String>(positional, 0, 'name', 'MyClass');

// Coerce D4rt list to typed list
final items = D4.coerceList<Item>(positional[0], 'items');

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

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 Properties

activeVisitor → InterpreterVisitor?
Exposes the currently-active visitor to embedders that need to finish unwrapping an InterpretedInstance after executeBundle has returned (e.g. FlutterD4rt._unwrap<Widget> turning a script-returned StatelessWidget InterpretedInstance into a native proxy via the registered interface factories).
no setter
nativeRegistrationCount → int
Number of native→interpreted registrations recorded since the last resetNativeAccumulators (OPEN B.12 / §U28 instrumentation).
no setter
usageHitCount → int
Total hit events recorded across all categories.
no setter
usageHits → Map<String, int>
Hits accumulated so far, keyed category|base|typeArg. Read-only copy.
no setter
usageLogEnabled ↔ bool
Opt-in instrumentation toggle. When true, extractBridgedArg and the interpreter's generic-constructor path record each relaxer / interface-proxy / type-coercion / generic-constructor hit and each unresolved miss, keyed by category + base type + type-argument. The accumulated data drives the mass-generation reduction work: it reveals which generated cases real scripts actually exercise.
getter/setter pair
usageMissCount → int
Total miss events recorded.
no setter
usageMisses → Map<String, int>
Misses accumulated so far, keyed miss|base|typeArg. Read-only copy.
no setter

Static Methods

callInterpreterCallback(InterpreterVisitor visitor, Object? callback, List<Object?> args, [Map<String, Object?> namedArgs = const {}]) → Object?
Call an interpreter callback that may be either an InterpretedFunction or a NativeFunction.
castCallbackResult<R>(Object? result) → R
ENG-011: Safely cast a callback result to the expected type R.
checkArity(List<Object?> positional, String memberDescription, {int? exactly, int? atMost, int? atLeast}) → void
SCC85: reject positional arguments the adapter would silently discard.
coerceByteStream(Object? arg, String paramName) → Stream<List<int>>
Coerce a stream of byte chunks that came from d4rt into a Stream<List<int>>.
coerceCallableToFunction(InterpreterVisitor visitor, Object? value) → Object?
GEN-110: Wrap a Callable (typically an InterpretedFunction) as a native Dart function value, so it can be passed to native code that expects a typed Function argument — e.g. VoidCallback, ValueChanged<T>, StateSetter, (BuildContext) => Widget.
coerceList<T>(Object? arg, String paramName) → List<T>
Coerce a List from D4rt to a typed List.
coerceListOrNull<T>(Object? arg, String paramName) → List<T>?
Coerce a List from D4rt, returning null if arg is null.
coerceMap<K, V>(Object? arg, String paramName, [InterpreterVisitor? visitor]) → Map<K, V>
Coerce a Map from D4rt to a typed Map.
coerceMapOrNull<K, V>(Object? arg, String paramName, [InterpreterVisitor? visitor]) → Map<K, V>?
Coerce a Map from D4rt, returning null if arg is null.
coerceNestedList<T>(Object? arg, String paramName) → List<List<T>>
Coerce a nested List<List<T>> from D4rt.
coerceNestedListOrNull<T>(Object? arg, String paramName) → List<List<T>>?
GEN-096 (D8g): nullable variant of coerceNestedList. Returns null if arg is null, otherwise delegates to coerceNestedList. Used by the bridge generator for parameters typed List<List<T>>?.
coerceSet<T>(Object? arg, String paramName) → Set<T>
Coerce a Set from D4rt to a typed Set.
coerceSetOrNull<T>(Object? arg, String paramName) → Set<T>?
Coerce a Set from D4rt, returning null if arg is null.
coerceStream<T>(Object? arg, String paramName) → Stream<T>
Coerce a stream that came from d4rt into a typed Stream<T>.
describeArityError(Object error, List<Object?> positional, String memberDescription) → String?
SCB28: restate a raw list RangeError as a wrong-arity diagnostic.
extractBridgedArg<T>(Object? arg, String paramName, [InterpreterVisitor? visitor]) → T
Extract a typed value from a BridgedInstance or native object.
extractBridgedArgOrNull<T>(Object? arg, String paramName, [InterpreterVisitor? visitor]) → T?
Extract a typed value from a BridgedInstance or native object, returning null if the argument is null.
findBridgedMethodInterceptor(String className, String methodName) → BridgedMethodAdapter?
Look up a bridged method interceptor for (className, methodName). Returns null when no interceptor has been registered.
findBridgedStaticMethodInterceptor(String className, String methodName) → BridgedStaticMethodAdapter?
Look up a bridged static method interceptor for (className, methodName). Returns null when no interceptor has been registered.
findEnumStaticGetter(String enumName, String getterName) → Object? Function()?
Look up a runtime-registered static getter for a bridged enum.
findGenericConstructor(String className, String constructorName) → BridgedStaticMethodAdapter?
Look up a registered generic constructor factory.
findSupplementaryMethod(String bridgedClassName, String methodName) → BridgedMethodAdapter?
Look up a supplementary method adapter.
getNamedArgWithDefault<T>(Map<String, Object?> named, String paramName, T defaultValue) → T
Get an optional named argument with default value.
getOptionalArg<T>(List<Object?> positional, int index, String paramName) → T?
Get an optional positional argument with type checking.
getOptionalArgWithDefault<T>(List<Object?> positional, int index, String paramName, T defaultValue) → T
Get an optional positional argument with default value.
getOptionalNamedArg<T>(Map<String, Object?> named, String paramName) → T?
Get an optional named argument with type checking.
getRequiredArg<T>(List<Object?> positional, int index, String paramName, String methodName) → T
Get a required positional argument, bounds-checked and type-extracted.
getRequiredArgTodoDefault<T>(List<Object?> positional, int index, String paramName, String methodName, String originalDefault) → T
Helper for parameters with non-wrappable defaults.
getRequiredNamedArg<T>(Map<String, Object?> named, String paramName, String methodName) → T
Get a required named argument with type checking.
getRequiredNamedArgTodoDefault<T>(Map<String, Object?> named, String paramName, String methodName, String originalDefault) → T
Helper for named parameters with non-wrappable defaults.
hasInterfaceProxy(String bridgedTypeName) → bool
Returns true when an interface-proxy factory has been registered for the bridged type bridgedTypeName (via registerInterfaceProxy).
interpretedForNative(Object? nativeObject) → Object?
Returns the InterpretedInstance previously registered for nativeObject, or null if none. The return type is Object? to avoid a cross-module import of InterpretedInstance here; callers in the interpreter cast to InterpretedInstance.
markProxyCapturesSuperArgs(String bridgedTypeName) → void
Mark bridgedTypeName as a proxy that needs super(...) args captured onto the InterpretedInstance. See _superArgCapturingProxies.
popActiveVisitor(InterpreterVisitor? previous) → void
Restores the active visitor saved by pushActiveVisitor. Always call this from a finally so the active visitor unwinds correctly on every exit path (including exceptions).
proxyCapturesSuperArgs(String bridgedTypeName) → bool
Returns true when the proxy registered for bridgedTypeName needs the script's super(...) argument list captured. See _superArgCapturingProxies.
pushActiveVisitor(InterpreterVisitor visitor) → InterpreterVisitor?
Sets visitor as the active visitor and returns the previously-active one.
recordUsageHit(String category, String base, String typeArg) → void
Record a successful resolution of category (relaxer, proxy, coercion, or ctor) for base with typeArg. No-op unless usageLogEnabled; call sites still guard the flag to avoid key allocation when logging is off.
recordUsageMiss(String base, String typeArg) → void
Record an unresolved extractBridgedArg miss for base/typeArg.
registerBridgedMethodInterceptor(String className, String methodName, BridgedMethodAdapter interceptor) → void
Register an interceptor for a bridged method. Replaces any previously registered interceptor for the same (className, methodName) pair.
registerBridgedStaticMethodInterceptor(String className, String methodName, BridgedStaticMethodAdapter interceptor) → void
Register an interceptor for a bridged static method. Replaces any previously registered interceptor for the same (className, methodName) pair.
registerEnumStaticGetter(String enumName, String getterName, Object? getter()) → void
Register a static getter on a bridged enum type.
registerGenericConstructor(String className, String constructorName, GenericConstructorFactory factory) → void
Register a generic constructor factory for a bridged class.
registerGenericTypeWrapper(String baseTypeName, GenericTypeWrapperFactory factory) → void
Register a wrapper factory for a generic base type (additive).
registerInterfaceProxy(String bridgedTypeName, InterfaceProxyFactory factory) → void
Register a proxy factory for a bridged interface or abstract class.
registerInterpretedForNative(Object nativeObject, Object interpretedInstance) → void
Records that nativeObject is the bridged-super of interpretedInstance. No-op for non-Object keys (Expandos require Object keys).
registerSupplementaryMethod(String bridgedClassName, String methodName, BridgedMethodAdapter adapter) → void
Register a supplementary method adapter for a bridged class.
registerTypeCoercion({required Type sourceType, required Type targetType, required TypeCoercionFactory factory}) → void
Register a type coercion from one type to another.
requireExactArgs(List<Object?> positional, int count, String methodName) → void
Verify exact positional arguments count.
requireMinArgs(List<Object?> positional, int minCount, String methodName) → void
Verify minimum positional arguments count.
resetNativeAccumulators() → void
Clears the cross-build native-side accumulator (OPEN B.12 / §U28).
resetUsageLog() → void
Clear all accumulated usage data so the next run starts fresh.
tryCreateInterfaceProxyByName(String bridgedTypeName, InterpretedInstance instance, InterpreterVisitor visitor) → Object?
Try to create an interface proxy keyed by the bridged-type name.
tryCreateInterfaceProxyWithVisitor<T>(InterpretedInstance instance, InterpreterVisitor visitor) → T?
Try to create an interface proxy with a visitor context.
typeName(Type t) → String
Returns the (memoized) toString() of t. See _typeNameCache.
unwrapAs<T>(Object? value, {InterpreterVisitor? visitor, String? expectedDescription}) → T
Unwrap an interpreter result to the requested native type T.
unwrapInterpreterValue(Object? value) → Object?
Unwrap an interpreter value to its native representation.
usageLogSummary() → String
A human-readable end-of-run summary of recorded hits and misses, grouped into Hits/Misses and sorted by descending count. Embedders print this at run end (the VM CLI does so automatically when the env var is set). Returns a short "(no … recorded)" line when nothing was captured.
validateTarget<T>(Object? target, String typeName) → T
Validate target type for instance methods/getters.
withActiveVisitor<T>(InterpreterVisitor visitor, T fn()) → T
Execute fn with the given visitor as the active visitor. Restores the previous visitor when done (supports nesting).