1 //===-- ExecutionContext.h --------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_TARGET_EXECUTIONCONTEXT_H 10 #define LLDB_TARGET_EXECUTIONCONTEXT_H 11 12 #include <mutex> 13 14 #include "lldb/Target/StackID.h" 15 #include "lldb/lldb-private.h" 16 17 namespace lldb_private { 18 19 //===----------------------------------------------------------------------===// 20 /// Execution context objects refer to objects in the execution of the program 21 /// that is being debugged. The consist of one or more of the following 22 /// objects: target, process, thread, and frame. Many objects in the debugger 23 /// need to track different executions contexts. For example, a local function 24 /// variable might have an execution context that refers to a stack frame. A 25 /// global or static variable might refer to a target since a stack frame 26 /// isn't required in order to evaluate a global or static variable (a process 27 /// isn't necessarily needed for a global variable since we might be able to 28 /// read the variable value from a data section in one of the object files in 29 /// a target). There are two types of objects that hold onto execution 30 /// contexts: ExecutionContextRef and ExecutionContext. Both of these objects 31 /// are described below. 32 /// 33 /// Not all objects in an ExecutionContext objects will be valid. If you want 34 /// to refer strongly (ExecutionContext) or weakly (ExecutionContextRef) to a 35 /// process, then only the process and target references will be valid. For 36 /// threads, only the thread, process and target references will be filled in. 37 /// For frames, all of the objects will be filled in. 38 /// 39 /// These classes are designed to be used as baton objects that get passed to 40 /// a wide variety of functions that require execution contexts. 41 //===----------------------------------------------------------------------===// 42 43 /// \class ExecutionContextRef ExecutionContext.h 44 /// "lldb/Target/ExecutionContext.h" 45 /// A class that holds a weak reference to an execution context. 46 /// 47 /// ExecutionContextRef objects are designed to hold onto an execution context 48 /// that might change over time. For example, if an object wants to refer to a 49 /// stack frame, it should hold onto an ExecutionContextRef to a frame object. 50 /// The backing object that represents the stack frame might change over time 51 /// and instances of this object can track the logical object that refers to a 52 /// frame even if it does change. 53 /// 54 /// These objects also don't keep execution objects around longer than they 55 /// should since they use weak pointers. For example if an object refers to a 56 /// stack frame and a stack frame is no longer in a thread, then a 57 /// ExecutionContextRef object that refers to that frame will not be able to 58 /// get a shared pointer to those objects since they are no longer around. 59 /// 60 /// ExecutionContextRef objects can also be used as objects in classes that 61 /// want to track a "previous execution context". Since the weak references to 62 /// the execution objects (target, process, thread and frame) don't keep these 63 /// objects around, they are safe to keep around. 64 /// 65 /// The general rule of thumb is all long lived objects that want to refer to 66 /// execution contexts should use ExecutionContextRef objects. The 67 /// ExecutionContext class is used to temporarily get shared pointers to any 68 /// execution context objects that are still around so they are guaranteed to 69 /// exist during a function that requires the objects. ExecutionContext 70 /// objects should NOT be used for long term storage since they will keep 71 /// objects alive with extra shared pointer references to these objects. 72 class ExecutionContextRef { 73 public: 74 /// Default Constructor. 75 ExecutionContextRef(); 76 77 /// Copy Constructor. 78 ExecutionContextRef(const ExecutionContextRef &rhs); 79 80 /// Construct using an ExecutionContext object that might be nullptr. 81 /// 82 /// If \a exe_ctx_ptr is valid, then make weak references to any valid 83 /// objects in the ExecutionContext, otherwise no weak references to any 84 /// execution context objects will be made. 85 ExecutionContextRef(const ExecutionContext *exe_ctx_ptr); 86 87 /// Construct using an ExecutionContext object. 88 /// 89 /// Make weak references to any valid objects in the ExecutionContext. 90 ExecutionContextRef(const ExecutionContext &exe_ctx); 91 92 /// Construct using the target and all the selected items inside of it (the 93 /// process and its selected thread, and the thread's selected frame). If 94 /// there is no selected thread, default to the first thread If there is no 95 /// selected frame, default to the first frame. 96 ExecutionContextRef(Target *target, bool adopt_selected); 97 98 /// Construct using an execution context scope. 99 /// 100 /// If the ExecutionContextScope object is valid and refers to a frame, make 101 /// weak references too the frame, thread, process and target. If the 102 /// ExecutionContextScope object is valid and refers to a thread, make weak 103 /// references too the thread, process and target. If the 104 /// ExecutionContextScope object is valid and refers to a process, make weak 105 /// references too the process and target. If the ExecutionContextScope 106 /// object is valid and refers to a target, make weak references too the 107 /// target. 108 ExecutionContextRef(ExecutionContextScope *exe_scope); 109 110 /// Construct using an execution context scope. 111 /// 112 /// If the ExecutionContextScope object refers to a frame, make weak 113 /// references too the frame, thread, process and target. If the 114 /// ExecutionContextScope object refers to a thread, make weak references 115 /// too the thread, process and target. If the ExecutionContextScope object 116 /// refers to a process, make weak references too the process and target. If 117 /// the ExecutionContextScope object refers to a target, make weak 118 /// references too the target. 119 ExecutionContextRef(ExecutionContextScope &exe_scope); 120 121 ~ExecutionContextRef(); 122 123 /// Assignment operator 124 /// 125 /// Copy all weak references in \a rhs. 126 ExecutionContextRef &operator=(const ExecutionContextRef &rhs); 127 128 /// Assignment operator from a ExecutionContext 129 /// 130 /// Make weak references to any strongly referenced objects in \a exe_ctx. 131 ExecutionContextRef &operator=(const ExecutionContext &exe_ctx); 132 133 /// Clear the object's state. 134 /// 135 /// Sets the process and thread to nullptr, and the frame index to an 136 /// invalid value. 137 void Clear(); 138 139 /// Set accessor that creates a weak reference to the target referenced in 140 /// \a target_sp. 141 /// 142 /// If \a target_sp is valid this object will create a weak reference to 143 /// that object, otherwise any previous target weak reference contained in 144 /// this object will be reset. 145 /// 146 /// Only the weak reference to the target will be updated, no other weak 147 /// references will be modified. If you want this execution context to make 148 /// a weak reference to the target's process, use the 149 /// ExecutionContextRef::SetContext() functions. 150 /// 151 /// \see ExecutionContextRef::SetContext(const lldb::TargetSP &, bool) 152 void SetTargetSP(const lldb::TargetSP &target_sp); 153 154 /// Set accessor that creates a weak reference to the process referenced in 155 /// \a process_sp. 156 /// 157 /// If \a process_sp is valid this object will create a weak reference to 158 /// that object, otherwise any previous process weak reference contained in 159 /// this object will be reset. 160 /// 161 /// Only the weak reference to the process will be updated, no other weak 162 /// references will be modified. If you want this execution context to make 163 /// a weak reference to the target, use the 164 /// ExecutionContextRef::SetContext() functions. 165 /// 166 /// \see ExecutionContextRef::SetContext(const lldb::ProcessSP &) 167 void SetProcessSP(const lldb::ProcessSP &process_sp); 168 169 /// Set accessor that creates a weak reference to the thread referenced in 170 /// \a thread_sp. 171 /// 172 /// If \a thread_sp is valid this object will create a weak reference to 173 /// that object, otherwise any previous thread weak reference contained in 174 /// this object will be reset. 175 /// 176 /// Only the weak reference to the thread will be updated, no other weak 177 /// references will be modified. If you want this execution context to make 178 /// a weak reference to the thread's process and target, use the 179 /// ExecutionContextRef::SetContext() functions. 180 /// 181 /// \see ExecutionContextRef::SetContext(const lldb::ThreadSP &) 182 void SetThreadSP(const lldb::ThreadSP &thread_sp); 183 184 /// Set accessor that creates a weak reference to the frame referenced in \a 185 /// frame_sp. 186 /// 187 /// If \a frame_sp is valid this object will create a weak reference to that 188 /// object, otherwise any previous frame weak reference contained in this 189 /// object will be reset. 190 /// 191 /// Only the weak reference to the frame will be updated, no other weak 192 /// references will be modified. If you want this execution context to make 193 /// a weak reference to the frame's thread, process and target, use the 194 /// ExecutionContextRef::SetContext() functions. 195 /// 196 /// \see ExecutionContextRef::SetContext(const lldb::StackFrameSP &) 197 void SetFrameSP(const lldb::StackFrameSP &frame_sp); 198 199 void SetTargetPtr(Target *target, bool adopt_selected); 200 201 void SetProcessPtr(Process *process); 202 203 void SetThreadPtr(Thread *thread); 204 205 void SetFramePtr(StackFrame *frame); 206 207 /// Get accessor that creates a strong reference from the weak target 208 /// reference contained in this object. 209 /// 210 /// \returns 211 /// A shared pointer to a target that is not guaranteed to be valid. 212 lldb::TargetSP GetTargetSP() const; 213 214 /// Get accessor that creates a strong reference from the weak process 215 /// reference contained in this object. 216 /// 217 /// \returns 218 /// A shared pointer to a process that is not guaranteed to be valid. 219 lldb::ProcessSP GetProcessSP() const; 220 221 /// Get accessor that creates a strong reference from the weak thread 222 /// reference contained in this object. 223 /// 224 /// \returns 225 /// A shared pointer to a thread that is not guaranteed to be valid. 226 lldb::ThreadSP GetThreadSP() const; 227 228 /// Get accessor that creates a strong reference from the weak frame 229 /// reference contained in this object. 230 /// 231 /// \returns 232 /// A shared pointer to a frame that is not guaranteed to be valid. 233 lldb::StackFrameSP GetFrameSP() const; 234 235 /// Create an ExecutionContext object from this object. 236 /// 237 /// Create strong references to any execution context objects that are still 238 /// valid. Any of the returned shared pointers in the ExecutionContext 239 /// objects is not guaranteed to be valid. \returns 240 /// An execution context object that has strong references to 241 /// any valid weak references in this object. 242 ExecutionContext Lock(bool thread_and_frame_only_if_stopped) const; 243 244 /// Returns true if this object has a weak reference to a thread. The return 245 /// value is only an indication of whether this object has a weak reference 246 /// and does not indicate whether the weak reference is valid or not. HasThreadRef()247 bool HasThreadRef() const { return m_tid != LLDB_INVALID_THREAD_ID; } 248 249 /// Returns true if this object has a weak reference to a frame. The return 250 /// value is only an indication of whether this object has a weak reference 251 /// and does not indicate whether the weak reference is valid or not. HasFrameRef()252 bool HasFrameRef() const { return m_stack_id.IsValid(); } 253 ClearThread()254 void ClearThread() { 255 m_thread_wp.reset(); 256 m_tid = LLDB_INVALID_THREAD_ID; 257 } 258 ClearFrame()259 void ClearFrame() { m_stack_id.Clear(); } 260 261 protected: 262 // Member variables 263 lldb::TargetWP m_target_wp; ///< A weak reference to a target 264 lldb::ProcessWP m_process_wp; ///< A weak reference to a process 265 mutable lldb::ThreadWP m_thread_wp; ///< A weak reference to a thread 266 lldb::tid_t m_tid = LLDB_INVALID_THREAD_ID; ///< The thread ID that this 267 ///< object refers to in case the 268 /// backing object changes 269 StackID m_stack_id; ///< The stack ID that this object refers to in case the 270 ///backing object changes 271 }; 272 273 /// \class ExecutionContext ExecutionContext.h 274 /// "lldb/Target/ExecutionContext.h" 275 /// A class that contains an execution context. 276 /// 277 /// This baton object can be passed into any function that requires a context 278 /// that specifies a target, process, thread and frame. These objects are 279 /// designed to be used for short term execution context object storage while 280 /// a function might be trying to evaluate something that requires a thread or 281 /// frame. ExecutionContextRef objects can be used to initialize one of these 282 /// objects to turn the weak execution context object references to the 283 /// target, process, thread and frame into strong references (shared pointers) 284 /// so that functions can guarantee that these objects won't go away in the 285 /// middle of a function. 286 /// 287 /// ExecutionContext objects should be used as short lived objects (typically 288 /// on the stack) in order to lock down an execution context for local use and 289 /// for passing down to other functions that also require specific contexts. 290 /// They should NOT be used for long term storage, for long term storage use 291 /// ExecutionContextRef objects. 292 class ExecutionContext { 293 public: 294 /// Default Constructor. 295 ExecutionContext(); 296 297 // Copy constructor 298 ExecutionContext(const ExecutionContext &rhs); 299 300 // Adopt the target and optionally its current context. 301 ExecutionContext(Target *t, bool fill_current_process_thread_frame = true); 302 303 // Create execution contexts from shared pointers 304 ExecutionContext(const lldb::TargetSP &target_sp, bool get_process); 305 ExecutionContext(const lldb::ProcessSP &process_sp); 306 ExecutionContext(const lldb::ThreadSP &thread_sp); 307 ExecutionContext(const lldb::StackFrameSP &frame_sp); 308 309 // Create execution contexts from weak pointers 310 ExecutionContext(const lldb::TargetWP &target_wp, bool get_process); 311 ExecutionContext(const lldb::ProcessWP &process_wp); 312 ExecutionContext(const lldb::ThreadWP &thread_wp); 313 ExecutionContext(const lldb::StackFrameWP &frame_wp); 314 ExecutionContext(const ExecutionContextRef &exe_ctx_ref); 315 ExecutionContext(const ExecutionContextRef *exe_ctx_ref, 316 bool thread_and_frame_only_if_stopped = false); 317 318 // These two variants take in a locker, and grab the target, lock the API 319 // mutex into locker, then fill in the rest of the shared pointers. 320 ExecutionContext(const ExecutionContextRef &exe_ctx_ref, 321 std::unique_lock<std::recursive_mutex> &locker); 322 ExecutionContext(const ExecutionContextRef *exe_ctx_ref, 323 std::unique_lock<std::recursive_mutex> &locker); 324 // Create execution contexts from execution context scopes 325 ExecutionContext(ExecutionContextScope *exe_scope); 326 ExecutionContext(ExecutionContextScope &exe_scope); 327 328 /// Construct with process, thread, and frame index. 329 /// 330 /// Initialize with process \a p, thread \a t, and frame index \a f. 331 /// 332 /// \param[in] process 333 /// The process for this execution context. 334 /// 335 /// \param[in] thread 336 /// The thread for this execution context. 337 /// 338 /// \param[in] frame 339 /// The frame index for this execution context. 340 ExecutionContext(Process *process, Thread *thread = nullptr, 341 StackFrame *frame = nullptr); 342 343 ~ExecutionContext(); 344 345 ExecutionContext &operator=(const ExecutionContext &rhs); 346 347 bool operator==(const ExecutionContext &rhs) const; 348 349 bool operator!=(const ExecutionContext &rhs) const; 350 351 /// Clear the object's state. 352 /// 353 /// Sets the process and thread to nullptr, and the frame index to an 354 /// invalid value. 355 void Clear(); 356 357 RegisterContext *GetRegisterContext() const; 358 359 ExecutionContextScope *GetBestExecutionContextScope() const; 360 361 uint32_t GetAddressByteSize() const; 362 363 lldb::ByteOrder GetByteOrder() const; 364 365 /// Returns a pointer to the target object. 366 /// 367 /// The returned pointer might be nullptr. Calling HasTargetScope(), 368 /// HasProcessScope(), HasThreadScope(), or HasFrameScope() can help to pre- 369 /// validate this pointer so that this accessor can freely be used without 370 /// having to check for nullptr each time. 371 /// 372 /// \see ExecutionContext::HasTargetScope() const @see 373 /// ExecutionContext::HasProcessScope() const @see 374 /// ExecutionContext::HasThreadScope() const @see 375 /// ExecutionContext::HasFrameScope() const 376 Target *GetTargetPtr() const; 377 378 /// Returns a pointer to the process object. 379 /// 380 /// The returned pointer might be nullptr. Calling HasProcessScope(), 381 /// HasThreadScope(), or HasFrameScope() can help to pre-validate this 382 /// pointer so that this accessor can freely be used without having to check 383 /// for nullptr each time. 384 /// 385 /// \see ExecutionContext::HasProcessScope() const @see 386 /// ExecutionContext::HasThreadScope() const @see 387 /// ExecutionContext::HasFrameScope() const 388 Process *GetProcessPtr() const; 389 390 /// Returns a pointer to the thread object. 391 /// 392 /// The returned pointer might be nullptr. Calling HasThreadScope() or 393 /// HasFrameScope() can help to pre-validate this pointer so that this 394 /// accessor can freely be used without having to check for nullptr each 395 /// time. 396 /// 397 /// \see ExecutionContext::HasThreadScope() const @see 398 /// ExecutionContext::HasFrameScope() const GetThreadPtr()399 Thread *GetThreadPtr() const { return m_thread_sp.get(); } 400 401 /// Returns a pointer to the frame object. 402 /// 403 /// The returned pointer might be nullptr. Calling HasFrameScope(), can help 404 /// to pre-validate this pointer so that this accessor can freely be used 405 /// without having to check for nullptr each time. 406 /// 407 /// \see ExecutionContext::HasFrameScope() const GetFramePtr()408 StackFrame *GetFramePtr() const { return m_frame_sp.get(); } 409 410 /// Returns a reference to the target object. 411 /// 412 /// Clients should call HasTargetScope(), HasProcessScope(), 413 /// HasThreadScope(), or HasFrameScope() prior to calling this function to 414 /// ensure that this ExecutionContext object contains a valid target. 415 /// 416 /// \see ExecutionContext::HasTargetScope() const @see 417 /// ExecutionContext::HasProcessScope() const @see 418 /// ExecutionContext::HasThreadScope() const @see 419 /// ExecutionContext::HasFrameScope() const 420 Target &GetTargetRef() const; 421 422 /// Returns a reference to the process object. 423 /// 424 /// Clients should call HasProcessScope(), HasThreadScope(), or 425 /// HasFrameScope() prior to calling this function to ensure that this 426 /// ExecutionContext object contains a valid target. 427 /// 428 /// \see ExecutionContext::HasProcessScope() const @see 429 /// ExecutionContext::HasThreadScope() const @see 430 /// ExecutionContext::HasFrameScope() const 431 Process &GetProcessRef() const; 432 433 /// Returns a reference to the thread object. 434 /// 435 /// Clients should call HasThreadScope(), or HasFrameScope() prior to 436 /// calling this function to ensure that this ExecutionContext object 437 /// contains a valid target. 438 /// 439 /// \see ExecutionContext::HasThreadScope() const @see 440 /// ExecutionContext::HasFrameScope() const 441 Thread &GetThreadRef() const; 442 443 /// Returns a reference to the thread object. 444 /// 445 /// Clients should call HasFrameScope() prior to calling this function to 446 /// ensure that this ExecutionContext object contains a valid target. 447 /// 448 /// \see ExecutionContext::HasFrameScope() const 449 StackFrame &GetFrameRef() const; 450 451 /// Get accessor to get the target shared pointer. 452 /// 453 /// The returned shared pointer is not guaranteed to be valid. GetTargetSP()454 const lldb::TargetSP &GetTargetSP() const { return m_target_sp; } 455 456 /// Get accessor to get the process shared pointer. 457 /// 458 /// The returned shared pointer is not guaranteed to be valid. GetProcessSP()459 const lldb::ProcessSP &GetProcessSP() const { return m_process_sp; } 460 461 /// Get accessor to get the thread shared pointer. 462 /// 463 /// The returned shared pointer is not guaranteed to be valid. GetThreadSP()464 const lldb::ThreadSP &GetThreadSP() const { return m_thread_sp; } 465 466 /// Get accessor to get the frame shared pointer. 467 /// 468 /// The returned shared pointer is not guaranteed to be valid. GetFrameSP()469 const lldb::StackFrameSP &GetFrameSP() const { return m_frame_sp; } 470 471 /// Set accessor to set only the target shared pointer. 472 void SetTargetSP(const lldb::TargetSP &target_sp); 473 474 /// Set accessor to set only the process shared pointer. 475 void SetProcessSP(const lldb::ProcessSP &process_sp); 476 477 /// Set accessor to set only the thread shared pointer. 478 void SetThreadSP(const lldb::ThreadSP &thread_sp); 479 480 /// Set accessor to set only the frame shared pointer. 481 void SetFrameSP(const lldb::StackFrameSP &frame_sp); 482 483 /// Set accessor to set only the target shared pointer from a target 484 /// pointer. 485 void SetTargetPtr(Target *target); 486 487 /// Set accessor to set only the process shared pointer from a process 488 /// pointer. 489 void SetProcessPtr(Process *process); 490 491 /// Set accessor to set only the thread shared pointer from a thread 492 /// pointer. 493 void SetThreadPtr(Thread *thread); 494 495 /// Set accessor to set only the frame shared pointer from a frame pointer. 496 void SetFramePtr(StackFrame *frame); 497 498 // Set the execution context using a target shared pointer. 499 // 500 // If "target_sp" is valid, sets the target context to match and if 501 // "get_process" is true, sets the process shared pointer if the target 502 // currently has a process. 503 void SetContext(const lldb::TargetSP &target_sp, bool get_process); 504 505 // Set the execution context using a process shared pointer. 506 // 507 // If "process_sp" is valid, then set the process and target in this context. 508 // Thread and frame contexts will be cleared. If "process_sp" is not valid, 509 // all shared pointers are reset. 510 void SetContext(const lldb::ProcessSP &process_sp); 511 512 // Set the execution context using a thread shared pointer. 513 // 514 // If "thread_sp" is valid, then set the thread, process and target in this 515 // context. The frame context will be cleared. If "thread_sp" is not valid, 516 // all shared pointers are reset. 517 void SetContext(const lldb::ThreadSP &thread_sp); 518 519 // Set the execution context using a frame shared pointer. 520 // 521 // If "frame_sp" is valid, then set the frame, thread, process and target in 522 // this context If "frame_sp" is not valid, all shared pointers are reset. 523 void SetContext(const lldb::StackFrameSP &frame_sp); 524 525 /// Returns true the ExecutionContext object contains a valid target. 526 /// 527 /// This function can be called after initializing an ExecutionContext 528 /// object, and if it returns true, calls to GetTargetPtr() and 529 /// GetTargetRef() do not need to be checked for validity. 530 bool HasTargetScope() const; 531 532 /// Returns true the ExecutionContext object contains a valid target and 533 /// process. 534 /// 535 /// This function can be called after initializing an ExecutionContext 536 /// object, and if it returns true, calls to GetTargetPtr() and 537 /// GetTargetRef(), GetProcessPtr(), and GetProcessRef(), do not need to be 538 /// checked for validity. 539 bool HasProcessScope() const; 540 541 /// Returns true the ExecutionContext object contains a valid target, 542 /// process, and thread. 543 /// 544 /// This function can be called after initializing an ExecutionContext 545 /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(), 546 /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), and GetThreadRef() do 547 /// not need to be checked for validity. 548 bool HasThreadScope() const; 549 550 /// Returns true the ExecutionContext object contains a valid target, 551 /// process, thread and frame. 552 /// 553 /// This function can be called after initializing an ExecutionContext 554 /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(), 555 /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), GetThreadRef(), 556 /// GetFramePtr(), and GetFrameRef() do not need to be checked for validity. 557 bool HasFrameScope() const; 558 559 protected: 560 // Member variables 561 lldb::TargetSP m_target_sp; ///< The target that owns the process/thread/frame 562 lldb::ProcessSP m_process_sp; ///< The process that owns the thread/frame 563 lldb::ThreadSP m_thread_sp; ///< The thread that owns the frame 564 lldb::StackFrameSP m_frame_sp; ///< The stack frame in thread. 565 }; 566 567 } // namespace lldb_private 568 569 #endif // LLDB_TARGET_EXECUTIONCONTEXT_H 570