[Playgrounds] Add a new -playground-option flag to control which transforms to apply (#69355)

Generalize the existing `-playground-high-performance` flag into a set of options that control various aspects of the "playground transformation" in Sema.

This commit adds the first two of those controllable parts of the transform, matching what the existing flag already controls (scope entry/exit and function arguments), but in an extensible way. The intent is for this to be a scalable way to control a larger set of upcoming options.

So instead of a single flag, we represent the playground transform options as a set of well-defined choices, with a new `-playground-option` flag to individually enable or disable those options (when prefixed with "No", the corresponding option is instead disabled). Enabling an already-enabled option or disabling an already-disabled option is a no-op.

For compatibility, the existing `-playground-high-performance` flag causes "expensive" transforms to be disabled, as before. We can also leave it as a useful shorthand to include or exclude new options even in the future, based on their cost. There is a comment on the old function indicating that new code should use the more general form, but it remains for clients like LLDB until they can switch over.

The machinery for implementing the playground options is similar to how `Features.def` works, with a new `PlaygroundOptions.def` that defines the supported playground transform options.  Each playground definition specifies the name and description, as well as whether the option is enabled by default, and whether it's also enabled in the "high performance" case.

Adding a new option in the future only requires adding it to `PlaygroundOptions.def`, deciding whether it should be on or off by default, deciding whether it should also be on or off in `-playground-high-performance` mode, and checking for its presence from the appropriate places in `PlaygroundTransform.cpp`.

Note that this is intended to control the types of user-visible results that the invoker of the compiler wants, from an externally detectable standpoint. Other flags, such as whether or not to use the extended form of the callbacks, remain as experimental features, since those deal with the mechanics and not the desired observed behavior.

rdar://109911673

Author: abertelrud

include/swift/Basic/LangOptions.h

@@ -22,6 +22,7 @@
 #include "swift/Basic/FixedBitSet.h"
 #include "swift/Basic/FunctionBodySkipping.h"
 #include "swift/Basic/LLVM.h"
+#include "swift/Basic/PlaygroundOption.h"
 #include "swift/Basic/Version.h"
 #include "swift/Config.h"
 #include "clang/CAS/CASOptions.h"
@@ -302,9 +303,8 @@ namespace swift {
     /// Indicates whether the playground transformation should be applied.
     bool PlaygroundTransform = false;
 
-    /// Indicates whether the playground transformation should omit
-    /// instrumentation that has a high runtime performance impact.
-    bool PlaygroundHighPerformance = false;
+    /// Indicates the specific playground transformations to apply.
+    PlaygroundOptionSet PlaygroundOptions;
 
     /// Keep comments during lexing and attach them to declarations.
     bool AttachCommentsToDecls = false;

include/swift/Basic/PlaygroundOption.h

@@ -0,0 +1,50 @@
+//===--- PlaygroundOption.h - Playground Transform Options -----*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2023 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef SWIFT_BASIC_PLAYGROUND_OPTIONS_H
+#define SWIFT_BASIC_PLAYGROUND_OPTIONS_H
+
+#include "llvm/ADT/Optional.h"
+#include "llvm/ADT/SmallSet.h"
+#include "llvm/ADT/StringRef.h"
+
+namespace swift {
+
+/// Enumeration describing all of the available playground options.
+enum class PlaygroundOption {
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+  OptionName,
+#include "swift/Basic/PlaygroundOptions.def"
+};
+
+constexpr unsigned numPlaygroundOptions() {
+  enum PlaygroundOptions {
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+    OptionName,
+#include "swift/Basic/PlaygroundOptions.def"
+    NumPlaygroundOptions
+  };
+  return NumPlaygroundOptions;
+}
+
+/// Return the name of the given playground option.
+llvm::StringRef getPlaygroundOptionName(PlaygroundOption option);
+
+/// Get the playground option that corresponds to a given name, if there is one.
+llvm::Optional<PlaygroundOption> getPlaygroundOption(llvm::StringRef name);
+
+/// Set of enabled playground options.
+typedef llvm::SmallSet<PlaygroundOption, 8> PlaygroundOptionSet;
+
+}
+
+#endif // SWIFT_BASIC_PLAYGROUND_OPTIONS_H

include/swift/Basic/PlaygroundOptions.def

@@ -0,0 +1,40 @@
+//===--- PlaygroundOptions.def - Playground Transform Options ---*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2023 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+//
+// This file defines options that can be specified for the playground transform.
+//
+//
+// PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn)
+//
+//   The PLAYGROUND_OPTION macro describes each named option that controls
+//   an aspect of the "playground transform" step in Sema.
+//
+//     OptionName: The name of this playground transform option (both in source
+//       code and as a `-playground` parameter), e.g. ScopeEvents
+//     Description: A string literal that describes the option, e.g. "Enables
+//       logging of scope entry and exit events"
+//     DefaultOn: Whether the option is enabled by default
+//     HighPerfOn: Whether the option is enabled in "high performance" mode
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef PLAYGROUND_OPTION
+#  error define PLAYGROUND_OPTION before including PlaygroundOptions.def
+#endif
+
+PLAYGROUND_OPTION(ScopeEvents, "Scope entry/exit events",
+  /* enabled by default */ true, /* enabled in high-perf mode */ false)
+
+PLAYGROUND_OPTION(FunctionParameters, "Values of function parameters",
+  /* enabled by default */ true, /* enabled in high-perf mode */ false)
+
+#undef PLAYGROUND_OPTION

include/swift/Option/FrontendOptions.td

@@ -848,6 +848,10 @@ def disable_standard_substitutions_in_reflection_mangling : Flag<["-"], "disable
 def playground : Flag<["-"], "playground">,
   HelpText<"Apply the playground semantics and transformation">;
 
+def playground_option : Separate<["-"], "playground-option">,
+  Flags<[FrontendOption]>,
+  HelpText<"Provide an option to the playground transform (if enabled)">;
+
 def playground_high_performance : Flag<["-"], "playground-high-performance">,
   HelpText<"Omit instrumentation that has a high runtime performance impact">;
 

include/swift/Subsystems.h

@@ -131,13 +131,26 @@ namespace swift {
   /// be compared against the results from the debugger.
   void performDebuggerTestingTransform(SourceFile &SF);
 
-  /// Once type checking is complete, this optionally transforms the ASTs to add
-  /// calls to external logging functions.
+  /// Once type checking is complete, this optionally transforms the ASTs to
+  /// insert calls to external logging functions.
+  ///
+  /// \param Opts The specific set of transforms that should be applied.
+  void performPlaygroundTransform(SourceFile &SF, PlaygroundOptionSet Opts);
+
+  /// Once type checking is complete, this optionally transforms the ASTs to
+  /// insert calls to external logging functions. This function is provided
+  /// for backward compatibility with existing code; for new code, the variant
+  /// that takes an `PlaygroundOptionSet` parameter should be used.
   ///
   /// \param HighPerformance True if the playground transform should omit
   /// instrumentation that has a high runtime performance impact.
+  ///
+  /// This function is provided for backward compatibility with older code, and
+  /// is a convenience for calling `performPlaygroundTransform()` with the set
+  /// of options that are enabled in high-performance mode. New uses should call
+  /// the newer form of this function that takes a `PlaygroundOptionSet`.
   void performPlaygroundTransform(SourceFile &SF, bool HighPerformance);
-  
+
   /// Once type checking is complete this optionally walks the ASTs to add calls
   /// to externally provided functions that simulate "program counter"-like
   /// debugging events. See the comment at the top of lib/Sema/PCMacro.cpp for a

lib/Basic/LangOptions.cpp

@@ -19,6 +19,7 @@
 #include "swift/AST/DiagnosticEngine.h"
 #include "swift/Basic/Feature.h"
 #include "swift/Basic/Platform.h"
+#include "swift/Basic/PlaygroundOption.h"
 #include "swift/Basic/Range.h"
 #include "swift/Config.h"
 #include "llvm/ADT/Hashing.h"
@@ -36,6 +37,11 @@ LangOptions::LangOptions() {
   Features.insert(Feature::ParserRoundTrip);
   Features.insert(Feature::ParserValidation);
 #endif
+  // Enable any playground options that are enabled by default.
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+  if (DefaultOn) \
+    PlaygroundOptions.insert(PlaygroundOption::OptionName);
+#include "swift/Basic/PlaygroundOptions.def"
 }
 
 struct SupportedConditionalValue {
@@ -638,6 +644,23 @@ bool swift::includeInModuleInterface(Feature feature) {
   llvm_unreachable("covered switch");
 }
 
+llvm::StringRef swift::getPlaygroundOptionName(PlaygroundOption option) {
+  switch (option) {
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+  case PlaygroundOption::OptionName: return #OptionName;
+#include "swift/Basic/PlaygroundOptions.def"
+  }
+  llvm_unreachable("covered switch");
+}
+
+llvm::Optional<PlaygroundOption> swift::getPlaygroundOption(llvm::StringRef name) {
+  return llvm::StringSwitch<llvm::Optional<PlaygroundOption>>(name)
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+  .Case(#OptionName, PlaygroundOption::OptionName)
+#include "swift/Basic/PlaygroundOptions.def"
+  .Default(llvm::None);
+}
+
 DiagnosticBehavior LangOptions::getAccessNoteFailureLimit() const {
   switch (AccessNoteBehavior) {
   case AccessNoteDiagnosticBehavior::Ignore:

lib/Frontend/CompilerInvocation.cpp

@@ -725,8 +725,26 @@ static bool ParseLangArgs(LangOptions &Opts, ArgList &Args,
   Opts.PlaygroundTransform |= Args.hasArg(OPT_playground);
   if (Args.hasArg(OPT_disable_playground_transform))
     Opts.PlaygroundTransform = false;
-  Opts.PlaygroundHighPerformance |=
-      Args.hasArg(OPT_playground_high_performance);
+  if (Args.hasArg(OPT_playground_high_performance)) {
+    // Disable any playground options that are marked as not being enabled in
+    // high performance mode.
+  #define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+    if (!HighPerfOn) \
+      Opts.PlaygroundOptions.erase(PlaygroundOption::OptionName);
+  #include "swift/Basic/PlaygroundOptions.def"
+  }
+  for (const Arg *A : Args.filtered(OPT_playground_option)) {
+    // Enable the option (or disable if it has a "No" prefix). Any unknown
+    // options are ignored.
+    StringRef optionName = A->getValue();
+    const bool disableOption = optionName.consume_front("No");
+    if (auto option = getPlaygroundOption(optionName)) {
+      if (disableOption)
+        Opts.PlaygroundOptions.erase(*option);
+      else
+        Opts.PlaygroundOptions.insert(*option);
+    }
+  }
 
   // This can be enabled independently of the playground transform.
   Opts.PCMacro |= Args.hasArg(OPT_pc_macro);

lib/Sema/PlaygroundTransform.cpp

@@ -23,6 +23,7 @@
 #include "swift/AST/Module.h"
 #include "swift/AST/Pattern.h"
 #include "swift/AST/SourceFile.h"
+#include "swift/Basic/PlaygroundOption.h"
 
 #include <random>
 #include <forward_list>
@@ -36,11 +37,20 @@ using namespace swift::instrumenter_support;
 
 namespace {
 
+struct TransformOptions {
+  bool LogScopeEvents;
+  bool LogFunctionParameters;
+
+  TransformOptions(const PlaygroundOptionSet &opts) :
+    LogScopeEvents(opts.contains(PlaygroundOption::ScopeEvents)),
+    LogFunctionParameters(opts.contains(PlaygroundOption::FunctionParameters)) {}
+};
+
 class Instrumenter : InstrumenterBase {
 private:
   std::mt19937_64 &RNG;
   unsigned &TmpNameIndex;
-  bool HighPerformance;
+  TransformOptions Options;
   bool ExtendedCallbacks;
 
   DeclNameRef DebugPrintName;
@@ -113,7 +123,7 @@ class Instrumenter : InstrumenterBase {
   // all the braces up to its target.
   size_t escapeToTarget(BracePair::TargetKinds TargetKind,
                         ElementVector &Elements, size_t EI) {
-    if (HighPerformance)
+    if (!Options.LogScopeEvents)
       return EI;
 
     for (const BracePair &BP : BracePairs) {
@@ -127,10 +137,9 @@ class Instrumenter : InstrumenterBase {
   }
 
 public:
-  Instrumenter(ASTContext &C, DeclContext *DC, std::mt19937_64 &RNG, bool HP,
-               unsigned &TmpNameIndex)
-      : InstrumenterBase(C, DC), RNG(RNG), TmpNameIndex(TmpNameIndex),
-        HighPerformance(HP),
+  Instrumenter(ASTContext &C, DeclContext *DC, std::mt19937_64 &RNG,
+               TransformOptions OPT, unsigned &TmpNameIndex)
+      : InstrumenterBase(C, DC), RNG(RNG), TmpNameIndex(TmpNameIndex), Options(OPT),
         ExtendedCallbacks(C.LangOpts.hasFeature(Feature::PlaygroundExtendedCallbacks)),
         DebugPrintName(C.getIdentifier("__builtin_debugPrint")),
         PrintName(C.getIdentifier("__builtin_print")),
@@ -609,7 +618,7 @@ class Instrumenter : InstrumenterBase {
     // If we were given any parameters that apply to this brace block, we insert
     // log calls for them now (before any of the other statements). We only log
     // named parameters (not `{ _ in ... }`, for example).
-    if (PL && !HighPerformance) {
+    if (PL && Options.LogFunctionParameters) {
       size_t EI = 0;
       for (const auto &PD : *PL) {
         if (PD->hasName()) {
@@ -627,7 +636,7 @@ class Instrumenter : InstrumenterBase {
       }
     }
 
-    if (!TopLevel && !HighPerformance && !BS->isImplicit()) {
+    if (!TopLevel && Options.LogScopeEvents && !BS->isImplicit()) {
       Elements.insert(Elements.begin(), *buildScopeEntry(BS->getSourceRange()));
       Elements.insert(Elements.end(), *buildScopeExit(BS->getSourceRange()));
     }
@@ -895,16 +904,17 @@ class Instrumenter : InstrumenterBase {
 
 } // end anonymous namespace
 
-void swift::performPlaygroundTransform(SourceFile &SF, bool HighPerformance) {
+void swift::performPlaygroundTransform(SourceFile &SF, PlaygroundOptionSet Opts) {
   class ExpressionFinder : public ASTWalker {
   private:
     ASTContext &ctx;
+    TransformOptions Options;
     std::mt19937_64 RNG;
-    bool HighPerformance;
     unsigned TmpNameIndex = 0;
 
   public:
-    ExpressionFinder(ASTContext &ctx, bool HP) : ctx(ctx), HighPerformance(HP) {}
+    ExpressionFinder(ASTContext &ctx, PlaygroundOptionSet Opts) :
+      ctx(ctx), Options(Opts) {}
 
     // FIXME: Remove this
     bool shouldWalkAccessorsTheOldWay() override { return true; }
@@ -918,7 +928,7 @@ void swift::performPlaygroundTransform(SourceFile &SF, bool HighPerformance) {
         if (!FD->isImplicit()) {
           if (BraceStmt *Body = FD->getBody()) {
             const ParameterList *PL = FD->getParameters();
-            Instrumenter I(ctx, FD, RNG, HighPerformance, TmpNameIndex);
+            Instrumenter I(ctx, FD, RNG, Options, TmpNameIndex);
             BraceStmt *NewBody = I.transformBraceStmt(Body, PL);
             if (NewBody != Body) {
               FD->setBody(NewBody, AbstractFunctionDecl::BodyKind::TypeChecked);
@@ -930,7 +940,7 @@ void swift::performPlaygroundTransform(SourceFile &SF, bool HighPerformance) {
       } else if (auto *TLCD = dyn_cast<TopLevelCodeDecl>(D)) {
         if (!TLCD->isImplicit()) {
           if (BraceStmt *Body = TLCD->getBody()) {
-            Instrumenter I(ctx, TLCD, RNG, HighPerformance, TmpNameIndex);
+            Instrumenter I(ctx, TLCD, RNG, Options, TmpNameIndex);
             BraceStmt *NewBody = I.transformBraceStmt(Body, nullptr, true);
             if (NewBody != Body) {
               TLCD->setBody(NewBody);
@@ -944,6 +954,20 @@ void swift::performPlaygroundTransform(SourceFile &SF, bool HighPerformance) {
     }
   };
 
-  ExpressionFinder EF(SF.getASTContext(), HighPerformance);
+  ExpressionFinder EF(SF.getASTContext(), Opts);
   SF.walk(EF);
 }
+
+/// This function is provided for backward compatibility with the old API, since
+/// LLDB and others call it directly, passing it a boolean to control whether to
+/// only apply "high performance" options. We emulate that here.
+void swift::performPlaygroundTransform(SourceFile &SF, bool HighPerformance) {
+  PlaygroundOptionSet HighPerfTransformOpts;
+  // Enable any playground options that are marked as being applicable to high
+  // performance mode.
+#define PLAYGROUND_OPTION(OptionName, Description, DefaultOn, HighPerfOn) \
+  if (HighPerfOn) \
+    HighPerfTransformOpts.insert(PlaygroundOption::OptionName);
+#include "swift/Basic/PlaygroundOptions.def"
+  swift::performPlaygroundTransform(SF, HighPerfTransformOpts);
+}

lib/Sema/TypeChecker.cpp

@@ -345,7 +345,7 @@ TypeCheckSourceFileRequest::evaluate(Evaluator &eval, SourceFile *SF) const {
   // Playground transform knows to look out for PCMacro's changes and not
   // to playground log them.
   if (!Ctx.hadError() && Ctx.LangOpts.PlaygroundTransform)
-    performPlaygroundTransform(*SF, Ctx.LangOpts.PlaygroundHighPerformance);
+    performPlaygroundTransform(*SF, Ctx.LangOpts.PlaygroundOptions);
 
   return std::make_tuple<>();
 }

test/PlaygroundTransform/high_performance.swift

@@ -1,13 +1,24 @@
+// Tests that `-playground-high-performance` turns off expensive logging, and
+// that turning off the corresponding options using `-playground-option` with
+// a `No` prefix does the same thing.
+//
+// REQUIRES: executable_test
+//
 // RUN: %empty-directory(%t)
 // RUN: cp %s %t/main.swift
 // RUN: %target-build-swift -whole-module-optimization -module-name PlaygroundSupport -emit-module-path %t/PlaygroundSupport.swiftmodule -parse-as-library -c -o %t/PlaygroundSupport.o %S/Inputs/SilentPCMacroRuntime.swift %S/Inputs/PlaygroundsRuntime.swift
+//
 // RUN: %target-build-swift -Xfrontend -playground -Xfrontend -playground-high-performance -o %t/main -I=%t %t/PlaygroundSupport.o %t/main.swift
 // RUN: %target-codesign %t/main
 // RUN: %target-run %t/main | %FileCheck %s
-// RUN: %target-build-swift -Xfrontend -pc-macro -Xfrontend -playground -Xfrontend -playground-high-performance -o %t/main2 -I=%t %t/PlaygroundSupport.o %t/main.swift 
+//
+// RUN: %target-build-swift -Xfrontend -pc-macro -Xfrontend -playground -Xfrontend -playground-high-performance -o %t/main2 -I=%t %t/PlaygroundSupport.o %t/main.swift
 // RUN: %target-codesign %t/main2
 // RUN: %target-run %t/main2 | %FileCheck %s
-// REQUIRES: executable_test
+//
+// RUN: %target-build-swift -Xfrontend -playground -Xfrontend -playground-option -Xfrontend NoScopeEvents -Xfrontend -playground-option -Xfrontend NoFunctionParameters -o %t/main3 -I=%t %t/PlaygroundSupport.o %t/main.swift
+// RUN: %target-codesign %t/main3
+// RUN: %target-run %t/main3 | %FileCheck %s
 
 import PlaygroundSupport