llvm/lldb/include/lldb/Target/ExecutionContext.h

//===-- ExecutionContext.h --------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_TARGET_EXECUTIONCONTEXT_H
#define LLDB_TARGET_EXECUTIONCONTEXT_H

#include <mutex>

#include "lldb/Target/StackID.h"
#include "lldb/lldb-private.h"

namespace lldb_private {

//===----------------------------------------------------------------------===//
/// Execution context objects refer to objects in the execution of the program
/// that is being debugged. The consist of one or more of the following
/// objects: target, process, thread, and frame. Many objects in the debugger
/// need to track different executions contexts. For example, a local function
/// variable might have an execution context that refers to a stack frame. A
/// global or static variable might refer to a target since a stack frame
/// isn't required in order to evaluate a global or static variable (a process
/// isn't necessarily needed for a global variable since we might be able to
/// read the variable value from a data section in one of the object files in
/// a target). There are two types of objects that hold onto execution
/// contexts: ExecutionContextRef and ExecutionContext. Both of these objects
/// are described below.
///
/// Not all objects in an ExecutionContext objects will be valid. If you want
/// to refer strongly (ExecutionContext) or weakly (ExecutionContextRef) to a
/// process, then only the process and target references will be valid. For
/// threads, only the thread, process and target references will be filled in.
/// For frames, all of the objects will be filled in.
///
/// These classes are designed to be used as baton objects that get passed to
/// a wide variety of functions that require execution contexts.
//===----------------------------------------------------------------------===//

/// \class ExecutionContextRef ExecutionContext.h
/// "lldb/Target/ExecutionContext.h"
/// A class that holds a weak reference to an execution context.
///
/// ExecutionContextRef objects are designed to hold onto an execution context
/// that might change over time. For example, if an object wants to refer to a
/// stack frame, it should hold onto an ExecutionContextRef to a frame object.
/// The backing object that represents the stack frame might change over time
/// and instances of this object can track the logical object that refers to a
/// frame even if it does change.
///
/// These objects also don't keep execution objects around longer than they
/// should since they use weak pointers. For example if an object refers to a
/// stack frame and a stack frame is no longer in a thread, then a
/// ExecutionContextRef object that refers to that frame will not be able to
/// get a shared pointer to those objects since they are no longer around.
///
/// ExecutionContextRef objects can also be used as objects in classes that
/// want to track a "previous execution context". Since the weak references to
/// the execution objects (target, process, thread and frame) don't keep these
/// objects around, they are safe to keep around.
///
/// The general rule of thumb is all long lived objects that want to refer to
/// execution contexts should use ExecutionContextRef objects. The
/// ExecutionContext class is used to temporarily get shared pointers to any
/// execution context objects that are still around so they are guaranteed to
/// exist during a function that requires the objects. ExecutionContext
/// objects should NOT be used for long term storage since they will keep
/// objects alive with extra shared pointer references to these  objects.
class ExecutionContextRef { … };

/// \class ExecutionContext ExecutionContext.h
/// "lldb/Target/ExecutionContext.h"
/// A class that contains an execution context.
///
/// This baton object can be passed into any function that requires a context
/// that specifies a target, process, thread and frame. These objects are
/// designed to be used for short term execution context object storage while
/// a function might be trying to evaluate something that requires a thread or
/// frame. ExecutionContextRef objects can be used to initialize one of these
/// objects to turn the weak execution context object references to the
/// target, process, thread and frame into strong references (shared pointers)
/// so that functions can guarantee that these objects won't go away in the
/// middle of a function.
///
/// ExecutionContext objects should be used as short lived objects (typically
/// on the stack) in order to lock down an execution context for local use and
/// for passing down to other functions that also require specific contexts.
/// They should NOT be used for long term storage, for long term storage use
/// ExecutionContextRef objects.
class ExecutionContext { … };

} // namespace lldb_private

#endif // LLDB_TARGET_EXECUTIONCONTEXT_H