providePackage method

bool providePackage(String packageName)

Step 7 — Grants packageName to this instance and reports whether its bridge definitions are already in the process-global pool.

Returns true → already pooled; the caller should skip registration and the pooled definitions are reused for this instance. Returns false → not pooled; the caller must register the package's bridges now. Those register* calls accumulate into the pool under packageName (because this call sets _currentProvidingPackage), so the next instance in the process gets true.

Either way packageName is added to this instance's _allowedPackages whitelist — only allowed packages are exposed in the interpreter environment (consumed by the warm-parent build in step 8).

Idempotent on packageName: calling it again for an already-provided package returns true (it is now pooled) and leaves the grant in place.

Canonical call site:

if (runner.providePackage('tom_d4rt_flutter') == false) {
  FlutterMaterialBridges.register(runner); // first instance pays the cost
  runner.registerExtensions('tom_d4rt_flutter', registerOverrides);
}
// here the package is registered AND allowed in this instance

Implementation

bool providePackage(String packageName) {
  _allowedPackages.add(packageName);
  final alreadyPooled = _packagePool.containsKey(packageName);
  if (alreadyPooled) {
    // Pooled already — the caller skips registration, so no package context
    // is opened. Clear any stale context from a prior provide call.
    _currentProvidingPackage = null;
    Logger.debugLazy(
      () => '[D4rtRunner.providePackage] "$packageName" already pooled — '
          'reusing pooled definitions.',
    );
    return true;
  }
  // First time this package is seen in the process: open the registration
  // context so the caller's register* calls land in the pool under this
  // package, and create the (empty) bundle now so an extension-only package
  // still has a home.
  _currentProvidingPackage = packageName;
  _bundleFor(packageName);
  Logger.debugLazy(
    () => '[D4rtRunner.providePackage] "$packageName" not pooled — caller '
        'must register; subsequent register* route into the pool.',
  );
  return false;
}