src/main/java/com/google/devtools/build/lib/syntax/Debug.java

// Copyright 2018 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.devtools.build.lib.syntax;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.lib.events.Location;
import java.util.concurrent.atomic.AtomicReference;

/** Debugger API. */
// TODO(adonovan): move Debugger to Debug.Debugger.
public final class Debug {

  private Debug() {} // uninstantiable

  static final AtomicReference<Debugger> debugger = new AtomicReference<>();

  /**
   * Installs a global hook that causes subsequently executed Starlark threads to notify the
   * debugger of important events. Closes any previously set debugger. Call {@code
   * setDebugger(null)} to disable debugging.
   */
  public static void setDebugger(Debugger dbg) {
    Debugger prev = debugger.getAndSet(dbg);
    if (prev != null) {
      prev.close();
    }
  }

  /**
   * Returns a copy of the current stack of call frames, outermost call first.
   *
   * <p>This function is intended for use only when execution of {@code thread} is stopped, for
   * example at a breakpoint. The resulting DebugFrames should not be retained after execution of
   * the thread has resumed. Most clients should instead use {@link StarlarkThread#getCallStack}.
   */
  public static ImmutableList<Frame> getCallStack(StarlarkThread thread) {
    return thread.getDebugCallStack();
  }

  /** Debugger interface to the interpreter's internal call frame representation. */
  public interface Frame {

    /** Returns function called in this frame. */
    StarlarkCallable getFunction();

    /** Returns the location of the current program counter. */
    Location getLocation();

    /** Returns the local environment of this frame. */
    ImmutableMap<String, Object> getLocals();
  }

  /**
   * Interface by which debugging tools are notified of a thread entering or leaving its top-level
   * frame.
   */
  public interface ThreadHook {
    void onPushFirst(StarlarkThread thread);

    void onPopLast(StarlarkThread thread);
  }

  static ThreadHook threadHook = null;

  /**
   * Installs a global hook that is notified each time a thread pushes or pops its top-level frame.
   * This interface is provided to support special tools; ordinary clients should have no need for
   * it.
   */
  public static void setThreadHook(ThreadHook hook) {
    threadHook = hook;
  }
}