1 /* Multi-process/thread control defs for GDB, the GNU debugger.
2 Copyright (C) 1987-2023 Free Software Foundation, Inc.
3 Contributed by Lynx Real-Time Systems, Inc. Los Gatos, CA.
6 This file is part of GDB.
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 3 of the License, or
11 (at your option) any later version.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with this program. If not, see <http://www.gnu.org/licenses/>. */
26 #include "breakpoint.h"
30 #include "target/waitstatus.h"
31 #include "target/target.h"
32 #include "cli/cli-utils.h"
33 #include "gdbsupport/refcounted-object.h"
34 #include "gdbsupport/common-gdbthread.h"
35 #include "gdbsupport/forward-scope-exit.h"
36 #include "displaced-stepping.h"
37 #include "gdbsupport/intrusive_list.h"
38 #include "thread-fsm.h"
41 struct process_stratum_target
;
43 /* When true, print debug messages related to GDB thread creation and
46 extern bool debug_threads
;
48 /* Print a "threads" debug statement. */
50 #define threads_debug_printf(fmt, ...) \
51 debug_prefixed_printf_cond (debug_threads, "threads", fmt, ##__VA_ARGS__)
53 /* Frontend view of the thread state. Possible extensions: stepping,
54 finishing, until(ling),...
56 NOTE: Since the thread state is not a boolean, most times, you do
57 not want to check it with negation. If you really want to check if
58 the thread is stopped,
62 if (tp->state == THREAD_STOPPED)
66 if (tp->state != THREAD_RUNNING)
68 The latter is also true for exited threads, most likely not what
72 /* In the frontend's perpective, the thread is stopped. */
75 /* In the frontend's perpective, the thread is running. */
78 /* The thread is listed, but known to have exited. We keep it
79 listed (but not visible) until it's safe to delete it. */
83 /* STEP_OVER_ALL means step over all subroutine calls.
84 STEP_OVER_UNDEBUGGABLE means step over calls to undebuggable functions.
85 STEP_OVER_NONE means don't step over any subroutine calls. */
87 enum step_over_calls_kind
91 STEP_OVER_UNDEBUGGABLE
94 /* Inferior thread specific part of `struct infcall_control_state'.
96 Inferior process counterpart is `struct inferior_control_state'. */
98 struct thread_control_state
100 /* User/external stepping state. */
102 /* Step-resume or longjmp-resume breakpoint. */
103 struct breakpoint
*step_resume_breakpoint
= nullptr;
105 /* Exception-resume breakpoint. */
106 struct breakpoint
*exception_resume_breakpoint
= nullptr;
108 /* Breakpoints used for software single stepping. Plural, because
109 it may have multiple locations. E.g., if stepping over a
110 conditional branch instruction we can't decode the condition for,
111 we'll need to put a breakpoint at the branch destination, and
112 another at the instruction after the branch. */
113 struct breakpoint
*single_step_breakpoints
= nullptr;
115 /* Range to single step within.
117 If this is nonzero, respond to a single-step signal by continuing
118 to step if the pc is in this range.
120 If step_range_start and step_range_end are both 1, it means to
121 step for a single instruction (FIXME: it might clean up
122 wait_for_inferior in a minor way if this were changed to the
123 address of the instruction and that address plus one. But maybe
125 CORE_ADDR step_range_start
= 0; /* Inclusive */
126 CORE_ADDR step_range_end
= 0; /* Exclusive */
128 /* Function the thread was in as of last it started stepping. */
129 struct symbol
*step_start_function
= nullptr;
131 /* If GDB issues a target step request, and this is nonzero, the
132 target should single-step this thread once, and then continue
133 single-stepping it without GDB core involvement as long as the
134 thread stops in the step range above. If this is zero, the
135 target should ignore the step range, and only issue one single
137 int may_range_step
= 0;
139 /* Stack frame address as of when stepping command was issued.
140 This is how we know when we step into a subroutine call, and how
141 to set the frame for the breakpoint used to step out. */
142 struct frame_id step_frame_id
{};
144 /* Similarly, the frame ID of the underlying stack frame (skipping
145 any inlined frames). */
146 struct frame_id step_stack_frame_id
{};
148 /* True if the the thread is presently stepping over a breakpoint or
149 a watchpoint, either with an inline step over or a displaced (out
150 of line) step, and we're now expecting it to report a trap for
151 the finished single step. */
152 int trap_expected
= 0;
154 /* Nonzero if the thread is being proceeded for a "finish" command
155 or a similar situation when return value should be printed. */
156 int proceed_to_finish
= 0;
158 /* Nonzero if the thread is being proceeded for an inferior function
162 enum step_over_calls_kind step_over_calls
= STEP_OVER_NONE
;
164 /* Nonzero if stopped due to a step command. */
167 /* Chain containing status of breakpoint(s) the thread stopped
169 bpstat
*stop_bpstat
= nullptr;
171 /* Whether the command that started the thread was a stepping
172 command. This is used to decide whether "set scheduler-locking
173 step" behaves like "on" or "off". */
174 int stepping_command
= 0;
177 /* Inferior thread specific part of `struct infcall_suspend_state'. */
179 struct thread_suspend_state
181 /* Last signal that the inferior received (why it stopped). When
182 the thread is resumed, this signal is delivered. Note: the
183 target should not check whether the signal is in pass state,
184 because the signal may have been explicitly passed with the
185 "signal" command, which overrides "handle nopass". If the signal
186 should be suppressed, the core will take care of clearing this
187 before the target is resumed. */
188 enum gdb_signal stop_signal
= GDB_SIGNAL_0
;
190 /* The reason the thread last stopped, if we need to track it
191 (breakpoint, watchpoint, etc.) */
192 enum target_stop_reason stop_reason
= TARGET_STOPPED_BY_NO_REASON
;
194 /* The waitstatus for this thread's last event. */
195 struct target_waitstatus waitstatus
;
196 /* If true WAITSTATUS hasn't been handled yet. */
197 int waitstatus_pending_p
= 0;
199 /* Record the pc of the thread the last time it stopped. (This is
200 not the current thread's PC as that may have changed since the
201 last stop, e.g., "return" command, or "p $pc = 0xf000").
203 - If the thread's PC has not changed since the thread last
204 stopped, then proceed skips a breakpoint at the current PC,
205 otherwise we let the thread run into the breakpoint.
207 - If the thread has an unprocessed event pending, as indicated by
208 waitstatus_pending_p, this is used in coordination with
209 stop_reason: if the thread's PC has changed since the thread
210 last stopped, a pending breakpoint waitstatus is discarded.
212 - If the thread is running, then this field has its value removed by
213 calling stop_pc.reset() (see thread_info::set_executing()).
214 Attempting to read a gdb::optional with no value is undefined
215 behaviour and will trigger an assertion error when _GLIBCXX_DEBUG is
216 defined, which should make error easier to track down. */
217 gdb::optional
<CORE_ADDR
> stop_pc
;
220 /* Base class for target-specific thread data. */
221 struct private_thread_info
223 virtual ~private_thread_info () = 0;
226 /* Unique pointer wrapper for private_thread_info. */
227 using private_thread_info_up
= std::unique_ptr
<private_thread_info
>;
229 /* Threads are intrusively refcounted objects. Being the
230 user-selected thread is normally considered an implicit strong
231 reference and is thus not accounted in the refcount, unlike
232 inferior objects. This is necessary, because there's no "current
233 thread" pointer. Instead the current thread is inferred from the
234 inferior_ptid global. However, when GDB needs to remember the
235 selected thread to later restore it, GDB bumps the thread object's
236 refcount, to prevent something deleting the thread object before
237 reverting back (e.g., due to a "kill" command). If the thread
238 meanwhile exits before being re-selected, then the thread object is
239 left listed in the thread list, but marked with state
240 THREAD_EXITED. (See scoped_restore_current_thread and
241 delete_thread). All other thread references are considered weak
242 references. Placing a thread in the thread list is an implicit
243 strong reference, and is thus not accounted for in the thread's
246 The intrusive_list_node base links threads in a per-inferior list. */
248 class thread_info
: public refcounted_object
,
249 public intrusive_list_node
<thread_info
>
252 explicit thread_info (inferior
*inf
, ptid_t ptid
);
255 bool deletable () const;
257 /* Mark this thread as running and notify observers. */
258 void set_running (bool running
);
260 ptid_t ptid
; /* "Actual process id";
261 In fact, this may be overloaded with
262 kernel thread id, etc. */
264 /* Each thread has two GDB IDs.
266 a) The thread ID (Id). This consists of the pair of:
268 - the number of the thread's inferior and,
270 - the thread's thread number in its inferior, aka, the
271 per-inferior thread number. This number is unique in the
272 inferior but not unique between inferiors.
274 b) The global ID (GId). This is a a single integer unique
275 between all inferiors.
279 (gdb) info threads -gid
280 Id GId Target Id Frame
281 * 1.1 1 Thread A 0x16a09237 in foo () at foo.c:10
282 1.2 3 Thread B 0x15ebc6ed in bar () at foo.c:20
283 1.3 5 Thread C 0x15ebc6ed in bar () at foo.c:20
284 2.1 2 Thread A 0x16a09237 in foo () at foo.c:10
285 2.2 4 Thread B 0x15ebc6ed in bar () at foo.c:20
286 2.3 6 Thread C 0x15ebc6ed in bar () at foo.c:20
288 Above, both inferiors 1 and 2 have threads numbered 1-3, but each
289 thread has its own unique global ID. */
291 /* The thread's global GDB thread number. This is exposed to MI,
292 Python/Scheme, visible with "info threads -gid", and is also what
293 the $_gthread convenience variable is bound to. */
296 /* The per-inferior thread number. This is unique in the inferior
297 the thread belongs to, but not unique between inferiors. This is
298 what the $_thread convenience variable is bound to. */
301 /* The inferior this thread belongs to. */
302 struct inferior
*inf
;
304 /* The user-given name of the thread.
306 Returns nullptr if the thread does not have a user-given name. */
307 const char *name () const
309 return m_name
.get ();
312 /* Set the user-given name of the thread.
314 Pass nullptr to clear the name. */
315 void set_name (gdb::unique_xmalloc_ptr
<char> name
)
317 m_name
= std::move (name
);
320 bool executing () const
321 { return m_executing
; }
323 /* Set the thread's 'm_executing' field from EXECUTING, and if EXECUTING
324 is true also clears the thread's stop_pc. */
325 void set_executing (bool executing
);
327 bool resumed () const
328 { return m_resumed
; }
330 /* Set the thread's 'm_resumed' field from RESUMED. The thread may also
331 be added to (when RESUMED is true), or removed from (when RESUMED is
332 false), the list of threads with a pending wait status. */
333 void set_resumed (bool resumed
);
335 /* Frontend view of the thread state. Note that the THREAD_RUNNING/
336 THREAD_STOPPED states are different from EXECUTING. When the
337 thread is stopped internally while handling an internal event,
338 like a software single-step breakpoint, EXECUTING will be false,
339 but STATE will still be THREAD_RUNNING. */
340 enum thread_state state
= THREAD_STOPPED
;
342 /* State of GDB control of inferior thread execution.
343 See `struct thread_control_state'. */
344 thread_control_state control
;
346 /* Save M_SUSPEND to SUSPEND. */
348 void save_suspend_to (thread_suspend_state
&suspend
) const
353 /* Restore M_SUSPEND from SUSPEND. */
355 void restore_suspend_from (const thread_suspend_state
&suspend
)
360 /* Return this thread's stop PC. This should only be called when it is
361 known that stop_pc has a value. If this function is being used in a
362 situation where a thread may not have had a stop_pc assigned, then
363 stop_pc_p() can be used to check if the stop_pc is defined. */
365 CORE_ADDR
stop_pc () const
367 gdb_assert (m_suspend
.stop_pc
.has_value ());
368 return *m_suspend
.stop_pc
;
371 /* Set this thread's stop PC. */
373 void set_stop_pc (CORE_ADDR stop_pc
)
375 m_suspend
.stop_pc
= stop_pc
;
378 /* Remove the stop_pc stored on this thread. */
380 void clear_stop_pc ()
382 m_suspend
.stop_pc
.reset ();
385 /* Return true if this thread has a cached stop pc value, otherwise
388 bool stop_pc_p () const
390 return m_suspend
.stop_pc
.has_value ();
393 /* Return true if this thread has a pending wait status. */
395 bool has_pending_waitstatus () const
397 return m_suspend
.waitstatus_pending_p
;
400 /* Get this thread's pending wait status.
402 May only be called if has_pending_waitstatus returns true. */
404 const target_waitstatus
&pending_waitstatus () const
406 gdb_assert (this->has_pending_waitstatus ());
408 return m_suspend
.waitstatus
;
411 /* Set this thread's pending wait status.
413 May only be called if has_pending_waitstatus returns false. */
415 void set_pending_waitstatus (const target_waitstatus
&ws
);
417 /* Clear this thread's pending wait status.
419 May only be called if has_pending_waitstatus returns true. */
421 void clear_pending_waitstatus ();
423 /* Return this thread's stop signal. */
425 gdb_signal
stop_signal () const
427 return m_suspend
.stop_signal
;
430 /* Set this thread's stop signal. */
432 void set_stop_signal (gdb_signal sig
)
434 m_suspend
.stop_signal
= sig
;
437 /* Return this thread's stop reason. */
439 target_stop_reason
stop_reason () const
441 return m_suspend
.stop_reason
;
444 /* Set this thread's stop reason. */
446 void set_stop_reason (target_stop_reason reason
)
448 m_suspend
.stop_reason
= reason
;
451 /* Get the FSM associated with the thread. */
453 struct thread_fsm
*thread_fsm () const
455 return m_thread_fsm
.get ();
458 /* Get the owning reference to the FSM associated with the thread.
460 After a call to this method, "thread_fsm () == nullptr". */
462 std::unique_ptr
<struct thread_fsm
> release_thread_fsm ()
464 return std::move (m_thread_fsm
);
467 /* Set the FSM associated with the current thread.
469 It is invalid to set the FSM if another FSM is already installed. */
471 void set_thread_fsm (std::unique_ptr
<struct thread_fsm
> fsm
)
473 gdb_assert (m_thread_fsm
== nullptr);
474 m_thread_fsm
= std::move (fsm
);
477 /* Record the thread options last set for this thread. */
479 void set_thread_options (gdb_thread_options thread_options
);
481 /* Get the thread options last set for this thread. */
483 gdb_thread_options
thread_options () const
485 return m_thread_options
;
488 int current_line
= 0;
489 struct symtab
*current_symtab
= NULL
;
491 /* Internal stepping state. */
493 /* Record the pc of the thread the last time it was resumed. (It
494 can't be done on stop as the PC may change since the last stop,
495 e.g., "return" command, or "p $pc = 0xf000"). This is maintained
496 by proceed and keep_going, and among other things, it's used in
497 adjust_pc_after_break to distinguish a hardware single-step
498 SIGTRAP from a breakpoint SIGTRAP. */
499 CORE_ADDR prev_pc
= 0;
501 /* Did we set the thread stepping a breakpoint instruction? This is
502 used in conjunction with PREV_PC to decide whether to adjust the
504 int stepped_breakpoint
= 0;
506 /* Should we step over breakpoint next time keep_going is called? */
507 int stepping_over_breakpoint
= 0;
509 /* Should we step over a watchpoint next time keep_going is called?
510 This is needed on targets with non-continuable, non-steppable
512 int stepping_over_watchpoint
= 0;
514 /* Set to TRUE if we should finish single-stepping over a breakpoint
515 after hitting the current step-resume breakpoint. The context here
516 is that GDB is to do `next' or `step' while signal arrives.
517 When stepping over a breakpoint and signal arrives, GDB will attempt
518 to skip signal handler, so it inserts a step_resume_breakpoint at the
519 signal return address, and resume inferior.
520 step_after_step_resume_breakpoint is set to TRUE at this moment in
521 order to keep GDB in mind that there is still a breakpoint to step over
522 when GDB gets back SIGTRAP from step_resume_breakpoint. */
523 int step_after_step_resume_breakpoint
= 0;
525 /* This is used to remember when a fork or vfork event was caught by
526 a catchpoint, and thus the event is to be followed at the next
527 resume of the thread, and not immediately. */
528 struct target_waitstatus pending_follow
;
530 /* True if this thread has been explicitly requested to stop. */
531 int stop_requested
= 0;
533 /* The initiating frame of a nexting operation, used for deciding
534 which exceptions to intercept. If it is null_frame_id no
535 bp_longjmp or bp_exception but longjmp has been caught just for
536 bp_longjmp_call_dummy. */
537 struct frame_id initiating_frame
= null_frame_id
;
539 /* Private data used by the target vector implementation. */
540 private_thread_info_up priv
;
542 /* Branch trace information for this thread. */
543 struct btrace_thread_info btrace
{};
545 /* Flag which indicates that the stack temporaries should be stored while
546 evaluating expressions. */
547 bool stack_temporaries_enabled
= false;
549 /* Values that are stored as temporaries on stack while evaluating
551 std::vector
<struct value
*> stack_temporaries
;
553 /* Step-over chain. A thread is in the step-over queue if this node is
555 intrusive_list_node
<thread_info
> step_over_list_node
;
557 /* Node for list of threads that are resumed and have a pending wait status.
559 The list head for this is in process_stratum_target, hence all threads in
560 this list belong to that process target. */
561 intrusive_list_node
<thread_info
> resumed_with_pending_wait_status_node
;
563 /* Displaced-step state for this thread. */
564 displaced_step_thread_state displaced_step_state
;
567 /* True if this thread is resumed from infrun's perspective.
568 Note that a thread can be marked both as not-executing and
569 resumed at the same time. This happens if we try to resume a
570 thread that has a wait status pending. We shouldn't let the
571 thread really run until that wait status has been processed, but
572 we should not process that wait status if we didn't try to let
574 bool m_resumed
= false;
576 /* True means the thread is executing. Note: this is different
577 from saying that there is an active target and we are stopped at
578 a breakpoint, for instance. This is a real indicator whether the
579 thread is off and running. */
580 bool m_executing
= false;
582 /* State of inferior thread to restore after GDB is done with an inferior
583 call. See `struct thread_suspend_state'. */
584 thread_suspend_state m_suspend
;
586 /* The user-given name of the thread.
588 Nullptr if the thread does not have a user-given name. */
589 gdb::unique_xmalloc_ptr
<char> m_name
;
591 /* Pointer to the state machine manager object that handles what is
592 left to do for the thread's execution command after the target
593 stops. Several execution commands use it. */
594 std::unique_ptr
<struct thread_fsm
> m_thread_fsm
;
596 /* The thread options as last set with a call to
597 set_thread_options. */
598 gdb_thread_options m_thread_options
;
601 using thread_info_resumed_with_pending_wait_status_node
602 = intrusive_member_node
<thread_info
,
603 &thread_info::resumed_with_pending_wait_status_node
>;
604 using thread_info_resumed_with_pending_wait_status_list
605 = intrusive_list
<thread_info
,
606 thread_info_resumed_with_pending_wait_status_node
>;
608 /* A gdb::ref_ptr pointer to a thread_info. */
610 using thread_info_ref
611 = gdb::ref_ptr
<struct thread_info
, refcounted_object_ref_policy
>;
613 /* A gdb::ref_ptr pointer to an inferior. This would ideally be in
614 inferior.h, but it can't due to header dependencies (inferior.h
615 includes gdbthread.h). */
618 = gdb::ref_ptr
<struct inferior
, refcounted_object_ref_policy
>;
620 /* Create an empty thread list, or empty the existing one. */
621 extern void init_thread_list (void);
623 /* Add a thread to the thread list, print a message
624 that a new thread is found, and return the pointer to
625 the new thread. Caller my use this pointer to
626 initialize the private thread data. */
627 extern struct thread_info
*add_thread (process_stratum_target
*targ
,
630 /* Same as add_thread, but does not print a message about new
632 extern struct thread_info
*add_thread_silent (process_stratum_target
*targ
,
635 /* Same as add_thread, and sets the private info. */
636 extern struct thread_info
*add_thread_with_info (process_stratum_target
*targ
,
638 private_thread_info_up
);
640 /* Delete thread THREAD and notify of thread exit. If the thread is
641 currently not deletable, don't actually delete it but still tag it
642 as exited and do the notification. EXIT_CODE is the thread's exit
643 code. If SILENT, don't actually notify the CLI. THREAD must not
644 be NULL or an assertion will fail. */
645 extern void delete_thread_with_exit_code (thread_info
*thread
,
647 bool silent
= false);
649 /* Delete thread THREAD and notify of thread exit. If the thread is
650 currently not deletable, don't actually delete it but still tag it
651 as exited and do the notification. THREAD must not be NULL or an
652 assertion will fail. */
653 extern void delete_thread (thread_info
*thread
);
655 /* Like delete_thread, but be quiet about it. Used when the process
656 this thread belonged to has already exited, for example. */
657 extern void delete_thread_silent (struct thread_info
*thread
);
659 /* Mark the thread exited, but don't delete it or remove it from the
660 inferior thread list. EXIT_CODE is the thread's exit code, if
661 available. If SILENT, then don't inform the CLI about the
663 extern void set_thread_exited (thread_info
*tp
,
664 gdb::optional
<ULONGEST
> exit_code
= {},
665 bool silent
= false);
667 /* Delete a step_resume_breakpoint from the thread database. */
668 extern void delete_step_resume_breakpoint (struct thread_info
*);
670 /* Delete an exception_resume_breakpoint from the thread database. */
671 extern void delete_exception_resume_breakpoint (struct thread_info
*);
673 /* Delete the single-step breakpoints of thread TP, if any. */
674 extern void delete_single_step_breakpoints (struct thread_info
*tp
);
676 /* Check if the thread has software single stepping breakpoints
678 extern int thread_has_single_step_breakpoints_set (struct thread_info
*tp
);
680 /* Check whether the thread has software single stepping breakpoints
682 extern int thread_has_single_step_breakpoint_here (struct thread_info
*tp
,
683 const address_space
*aspace
,
686 /* Returns whether to show inferior-qualified thread IDs, or plain
687 thread numbers. Inferior-qualified IDs are shown whenever we have
688 multiple inferiors, or the only inferior left has number > 1. */
689 extern int show_inferior_qualified_tids (void);
691 /* Return a string version of THR's thread ID. If there are multiple
692 inferiors, then this prints the inferior-qualifier form, otherwise
693 it only prints the thread number. The result is stored in a
694 circular static buffer, NUMCELLS deep. */
695 const char *print_thread_id (struct thread_info
*thr
);
697 /* Like print_thread_id, but always prints the inferior-qualified form,
698 even when there is only a single inferior. */
699 const char *print_full_thread_id (struct thread_info
*thr
);
701 /* Boolean test for an already-known ptid. */
702 extern bool in_thread_list (process_stratum_target
*targ
, ptid_t ptid
);
704 /* Boolean test for an already-known global thread id (GDB's homegrown
705 global id, not the system's). */
706 extern int valid_global_thread_id (int global_id
);
708 /* Find thread by GDB global thread ID. */
709 struct thread_info
*find_thread_global_id (int global_id
);
711 /* Find thread by thread library specific handle in inferior INF. */
712 struct thread_info
*find_thread_by_handle
713 (gdb::array_view
<const gdb_byte
> handle
, struct inferior
*inf
);
715 /* Finds the first thread of the specified inferior. */
716 extern struct thread_info
*first_thread_of_inferior (inferior
*inf
);
718 /* Returns any thread of inferior INF, giving preference to the
720 extern struct thread_info
*any_thread_of_inferior (inferior
*inf
);
722 /* Returns any non-exited thread of inferior INF, giving preference to
723 the current thread, and to not executing threads. */
724 extern struct thread_info
*any_live_thread_of_inferior (inferior
*inf
);
726 /* Change the ptid of thread OLD_PTID to NEW_PTID. */
727 void thread_change_ptid (process_stratum_target
*targ
,
728 ptid_t old_ptid
, ptid_t new_ptid
);
730 /* Iterator function to call a user-provided callback function
731 once for each known thread. */
732 typedef int (*thread_callback_func
) (struct thread_info
*, void *);
733 extern struct thread_info
*iterate_over_threads (thread_callback_func
, void *);
735 /* Pull in the internals of the inferiors/threads ranges and
736 iterators. Must be done after struct thread_info is defined. */
737 #include "thread-iter.h"
739 /* Return a range that can be used to walk over threads, with
742 Used like this, it walks over all threads of all inferiors of all
745 for (thread_info *thr : all_threads ())
748 FILTER_PTID can be used to filter out threads that don't match.
751 - minus_one_ptid, meaning walk all threads of all inferiors of
752 PROC_TARGET. If PROC_TARGET is NULL, then of all targets.
754 - A process ptid, in which case walk all threads of the specified
755 process. PROC_TARGET must be non-NULL in this case.
757 - A thread ptid, in which case walk that thread only. PROC_TARGET
758 must be non-NULL in this case.
761 inline all_matching_threads_range
762 all_threads (process_stratum_target
*proc_target
= nullptr,
763 ptid_t filter_ptid
= minus_one_ptid
)
765 return all_matching_threads_range (proc_target
, filter_ptid
);
768 /* Return a range that can be used to walk over all non-exited threads
769 of all inferiors, with range-for. Arguments are like all_threads
772 inline all_non_exited_threads_range
773 all_non_exited_threads (process_stratum_target
*proc_target
= nullptr,
774 ptid_t filter_ptid
= minus_one_ptid
)
776 return all_non_exited_threads_range (proc_target
, filter_ptid
);
779 /* Return a range that can be used to walk over all threads of all
780 inferiors, with range-for, safely. I.e., it is safe to delete the
781 currently-iterated thread. When combined with range-for, this
782 allow convenient patterns like this:
784 for (thread_info *t : all_threads_safe ())
785 if (some_condition ())
789 inline all_threads_safe_range
792 return all_threads_safe_range (all_threads_iterator::begin_t
{});
795 extern int thread_count (process_stratum_target
*proc_target
);
797 /* Return true if we have any thread in any inferior. */
798 extern bool any_thread_p ();
800 /* Switch context to thread THR. */
801 extern void switch_to_thread (struct thread_info
*thr
);
803 /* Switch context to no thread selected. */
804 extern void switch_to_no_thread ();
806 /* Switch from one thread to another. Does not read registers. */
807 extern void switch_to_thread_no_regs (struct thread_info
*thread
);
809 /* Marks or clears thread(s) PTID of TARG as resumed. If PTID is
810 MINUS_ONE_PTID, applies to all threads of TARG. If
811 ptid_is_pid(PTID) is true, applies to all threads of the process
812 pointed at by {TARG,PTID}. */
813 extern void set_resumed (process_stratum_target
*targ
,
814 ptid_t ptid
, bool resumed
);
816 /* Marks thread PTID of TARG as running, or as stopped. If PTID is
817 minus_one_ptid, marks all threads of TARG. */
818 extern void set_running (process_stratum_target
*targ
,
819 ptid_t ptid
, bool running
);
821 /* Marks or clears thread(s) PTID of TARG as having been requested to
822 stop. If PTID is MINUS_ONE_PTID, applies to all threads of TARG.
823 If ptid_is_pid(PTID) is true, applies to all threads of the process
824 pointed at by {TARG, PTID}. If STOP, then the
825 THREAD_STOP_REQUESTED observer is called with PTID as argument. */
826 extern void set_stop_requested (process_stratum_target
*targ
,
827 ptid_t ptid
, bool stop
);
829 /* Marks thread PTID of TARG as executing, or not. If PTID is
830 minus_one_ptid, marks all threads of TARG.
832 Note that this is different from the running state. See the
833 description of state and executing fields of struct
835 extern void set_executing (process_stratum_target
*targ
,
836 ptid_t ptid
, bool executing
);
838 /* True if any (known or unknown) thread of TARG is or may be
840 extern bool threads_are_executing (process_stratum_target
*targ
);
842 /* Merge the executing property of thread PTID of TARG over to its
843 thread state property (frontend running/stopped view).
845 "not executing" -> "stopped"
846 "executing" -> "running"
849 If PTID is minus_one_ptid, go over all threads of TARG.
851 Notifications are only emitted if the thread state did change. */
852 extern void finish_thread_state (process_stratum_target
*targ
, ptid_t ptid
);
854 /* Calls finish_thread_state on scope exit, unless release() is called
856 using scoped_finish_thread_state
857 = FORWARD_SCOPE_EXIT (finish_thread_state
);
859 /* Commands with a prefix of `thread'. */
860 extern struct cmd_list_element
*thread_cmd_list
;
862 extern void thread_command (const char *tidstr
, int from_tty
);
864 /* Print notices on thread events (attach, detach, etc.), set with
865 `set print thread-events'. */
866 extern bool print_thread_events
;
868 /* Prints the list of threads and their details on UIOUT. If
869 REQUESTED_THREADS, a list of GDB ids/ranges, is not NULL, only
870 print threads whose ID is included in the list. If PID is not -1,
871 only print threads from the process PID. Otherwise, threads from
872 all attached PIDs are printed. If both REQUESTED_THREADS is not
873 NULL and PID is not -1, then the thread is printed if it belongs to
874 the specified process. Otherwise, an error is raised. */
875 extern void print_thread_info (struct ui_out
*uiout
,
876 const char *requested_threads
,
879 /* Save/restore current inferior/thread/frame. */
881 class scoped_restore_current_thread
884 scoped_restore_current_thread ();
885 ~scoped_restore_current_thread ();
887 scoped_restore_current_thread (scoped_restore_current_thread
&&rhs
);
889 DISABLE_COPY_AND_ASSIGN (scoped_restore_current_thread
);
891 /* Cancel restoring on scope exit. */
892 void dont_restore () { m_dont_restore
= true; }
897 bool m_dont_restore
= false;
898 thread_info_ref m_thread
;
901 frame_id m_selected_frame_id
;
902 int m_selected_frame_level
;
904 /* Save/restore the language as well, because selecting a frame
905 changes the current language to the frame's language if "set
907 enum language m_lang
;
910 /* Returns a pointer into the thread_info corresponding to
911 INFERIOR_PTID. INFERIOR_PTID *must* be in the thread list. */
912 extern struct thread_info
* inferior_thread (void);
914 extern void update_thread_list (void);
916 /* Delete any thread the target says is no longer alive. */
918 extern void prune_threads (void);
920 /* Delete threads marked THREAD_EXITED. Unlike prune_threads, this
921 does not consult the target about whether the thread is alive right
923 extern void delete_exited_threads (void);
925 /* Return true if PC is in the stepping range of THREAD. */
927 bool pc_in_thread_step_range (CORE_ADDR pc
, struct thread_info
*thread
);
929 /* Enable storing stack temporaries for thread THR and disable and
930 clear the stack temporaries on destruction. Holds a strong
933 class enable_thread_stack_temporaries
937 explicit enable_thread_stack_temporaries (struct thread_info
*thr
)
938 : m_thr (thread_info_ref::new_reference (thr
))
940 m_thr
->stack_temporaries_enabled
= true;
941 m_thr
->stack_temporaries
.clear ();
944 ~enable_thread_stack_temporaries ()
946 m_thr
->stack_temporaries_enabled
= false;
947 m_thr
->stack_temporaries
.clear ();
950 DISABLE_COPY_AND_ASSIGN (enable_thread_stack_temporaries
);
954 thread_info_ref m_thr
;
957 extern bool thread_stack_temporaries_enabled_p (struct thread_info
*tp
);
959 extern void push_thread_stack_temporary (struct thread_info
*tp
, struct value
*v
);
961 extern value
*get_last_thread_stack_temporary (struct thread_info
*tp
);
963 extern bool value_in_thread_stack_temporaries (struct value
*,
964 struct thread_info
*thr
);
966 /* Thread step-over list type. */
967 using thread_step_over_list_node
968 = intrusive_member_node
<thread_info
, &thread_info::step_over_list_node
>;
969 using thread_step_over_list
970 = intrusive_list
<thread_info
, thread_step_over_list_node
>;
971 using thread_step_over_list_iterator
972 = reference_to_pointer_iterator
<thread_step_over_list::iterator
>;
973 using thread_step_over_list_safe_iterator
974 = basic_safe_iterator
<thread_step_over_list_iterator
>;
975 using thread_step_over_list_safe_range
976 = iterator_range
<thread_step_over_list_safe_iterator
>;
978 static inline thread_step_over_list_safe_range
979 make_thread_step_over_list_safe_range (thread_step_over_list
&list
)
981 return thread_step_over_list_safe_range
982 (thread_step_over_list_safe_iterator (list
.begin (),
984 thread_step_over_list_safe_iterator (list
.end (),
988 /* Add TP to the end of the global pending step-over chain. */
990 extern void global_thread_step_over_chain_enqueue (thread_info
*tp
);
992 /* Append the thread step over list LIST to the global thread step over
995 extern void global_thread_step_over_chain_enqueue_chain
996 (thread_step_over_list
&&list
);
998 /* Remove TP from the global pending step-over chain. */
1000 extern void global_thread_step_over_chain_remove (thread_info
*tp
);
1002 /* Return true if TP is in any step-over chain. */
1004 extern int thread_is_in_step_over_chain (struct thread_info
*tp
);
1006 /* Return the length of the the step over chain TP is in.
1008 If TP is non-nullptr, the thread must be in a step over chain.
1009 TP may be nullptr, in which case it denotes an empty list, so a length of
1012 extern int thread_step_over_chain_length (const thread_step_over_list
&l
);
1014 /* Cancel any ongoing execution command. */
1016 extern void thread_cancel_execution_command (struct thread_info
*thr
);
1018 /* Check whether it makes sense to access a register of the current
1019 thread at this point. If not, throw an error (e.g., the thread is
1021 extern void validate_registers_access (void);
1023 /* Check whether it makes sense to access a register of THREAD at this point.
1024 Returns true if registers may be accessed; false otherwise. */
1025 extern bool can_access_registers_thread (struct thread_info
*thread
);
1027 /* Returns whether to show which thread hit the breakpoint, received a
1028 signal, etc. and ended up causing a user-visible stop. This is
1029 true iff we ever detected multiple threads. */
1030 extern int show_thread_that_caused_stop (void);
1032 /* Print the message for a thread or/and frame selected. */
1033 extern void print_selected_thread_frame (struct ui_out
*uiout
,
1034 user_selected_what selection
);
1036 /* Helper for the CLI's "thread" command and for MI's -thread-select.
1037 Selects thread THR. TIDSTR is the original string the thread ID
1038 was parsed from. This is used in the error message if THR is not
1040 extern void thread_select (const char *tidstr
, class thread_info
*thr
);
1042 /* Return THREAD's name.
1044 If THREAD has a user-given name, return it. Otherwise, query the thread's
1045 target to get the name. May return nullptr. */
1046 extern const char *thread_name (thread_info
*thread
);
1048 /* Switch to thread TP if it is alive. Returns true if successfully
1049 switched, false otherwise. */
1051 extern bool switch_to_thread_if_alive (thread_info
*thr
);
1053 /* Assuming that THR is the current thread, execute CMD.
1054 If ADA_TASK is not empty, it is the Ada task ID, and will
1055 be printed instead of the thread information.
1056 FLAGS.QUIET controls the printing of the thread information.
1057 FLAGS.CONT and FLAGS.SILENT control how to handle errors. Can throw an
1058 exception if !FLAGS.SILENT and !FLAGS.CONT and CMD fails. */
1060 extern void thread_try_catch_cmd (thread_info
*thr
,
1061 gdb::optional
<int> ada_task
,
1062 const char *cmd
, int from_tty
,
1063 const qcs_flags
&flags
);
1065 /* Return a string representation of STATE. */
1067 extern const char *thread_state_string (enum thread_state state
);
1069 #endif /* GDBTHREAD_H */