commit 09d1370d4f6d334d24059a9fe3b2f960658733d1
author adonovan <adonovan@google.com> Tue May 19 08:26:55 2020 -0700
committer Copybara-Service <copybara-worker@google.com> Tue May 19 08:27:56 2020 -0700
tree b32b1f0d9eb62b3952243c790af901fcb4ea2dad
parent 9ec7232bb753e6e65743c448973cd971c919ce04

bazel syntax: disentangle StarlarkThread and Module

New interpreter API (if you don't use a helper function):

To call a function:

   try (Mutability mu = Mutability.create("myexpr")) {
      StarlarkThread thread = new StarlarkThread(mu, semantics);
      return Starlark.call(thread, fn, args, kwargs);
   } catch (EvalException ex) {
       ...
   }

To execute a file:

   StarlarkFile file = ...
   Module module = Module.create(); // default environment
   Resolver.resolve(file, module);
   try (Mutability mu = Mutability.create("myfile")) {
      StarlarkThread thread = new StarlarkThread(mu, semantics);
      Starlark.exec(file, thread, module);
   } catch (EvalException ex) {
       ...
   }
   // Inv: module contains globals

Overview of change:

- Eliminate the concept of "a Starlark thread's module".
  A module is rightly associated with a Starlark function, not a thread.
  Consider a thread used just to call an existing function value, for example.
  (Previously, a module would always have been created even if unused.)

- Modules are now created explicitly, from a predeclared environment
  and a semantics, which is used for filtering but not retained.
  Modules can now be created before threads---the logical order.
  This simplifies a number of clients.

- Flatten Module. It is no longer a linked list. It contains only
   (predeclared, globals, clientData),
  and exportedGlobals which will go away soon.

- Simplify processing of FlagGuardedValues. They are either unwrapped
  (if enabled by semantics) or left as is, if disabled.
  This means they are visible through Module.getPredeclared.

- Delete Module.mutability. It is inessential and raises
  questions of consistency with StarlarkThread.
  What really matters is whether a module's global values are mutable.

- Delete StarlarkThread.Builder. A simple constructor now suffices:
   new StarlarkThread(Mutability, StarlarkSemantics).

- EvaluationTestCase now exposes two hooks for Module and Thread creation
  so that tests can predeclare bindings, set client data, and insert
  thread local values.  Creation of Module and Thread is now fully lazy.
  A follow-up change will eliminate the regrettable use of inheritance.

Also:

- Move ModuleCodec into Module, so that we don't need to harm its API.

- Use separate UNIVERSE and predeclared buckets in Module.
  The UNIVERSE is always implicitly available.
  The API doesn't fully separate them yet (needs Resolver work),
  but this should reduce the amount of map copying and redundant
  specification.

- Add more pre-evaluated expressions to ParamDescriptor.evalDefault
  so that we can bootstrap all the @Param annotation's default values
  used by Starlark.UNIVERSE without JVM deadlock. This breaks a cyclic
  dependency between the evaluator and UNIVERSE.

- Use composition not inheritance of EvaluationTestCase in more tests.

This is my 6th attempt at this change in as many months.

This is a breaking API change for Copybara.

PiperOrigin-RevId: 312284294