1 /* Thread command's finish-state machine, for GDB, the GNU debugger.
2    Copyright (C) 2015-2024 Free Software Foundation, Inc.
3 
4    This file is part of GDB.
5 
6    This program is free software; you can redistribute it and/or modify
7    it under the terms of the GNU General Public License as published by
8    the Free Software Foundation; either version 3 of the License, or
9    (at your option) any later version.
10 
11    This program is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14    GNU General Public License for more details.
15 
16    You should have received a copy of the GNU General Public License
17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
18 
19 #ifndef THREAD_FSM_H
20 #define THREAD_FSM_H
21 
22 #include "mi/mi-common.h"
23 
24 struct return_value_info;
25 struct thread_fsm_ops;
26 struct type;
27 struct value;
28 
29 /* The captured function return value/type and its position in the
30    value history.  */
31 
32 struct return_value_info
33 {
34   /* The captured return value.  May be NULL if we weren't able to
35      retrieve it.  See get_return_value.  */
36   struct value *value;
37 
38   /* The return type.  In some cases, we'll not be able extract the
39      return value, but we always know the type.  */
40   struct type *type;
41 
42   /* If we captured a value, this is the value history index.  */
43   int value_history_index;
44 };
45 
46 /* A thread finite-state machine structure contains the necessary info
47    and callbacks to manage the state machine protocol of a thread's
48    execution command.  */
49 
50 struct thread_fsm
51 {
thread_fsmthread_fsm52   explicit thread_fsm (struct interp *cmd_interp)
53     : command_interp (cmd_interp)
54   {
55   }
56 
57   /* The destructor.  This should simply free heap allocated data
58      structures.  Cleaning up target resources (like, e.g.,
59      breakpoints) should be done in the clean_up method.  */
60   virtual ~thread_fsm () = default;
61 
62   DISABLE_COPY_AND_ASSIGN (thread_fsm);
63 
64   /* Called to clean up target resources after the FSM.  E.g., if the
65      FSM created internal breakpoints, this is where they should be
66      deleted.  */
clean_upthread_fsm67   virtual void clean_up (struct thread_info *thread)
68   {
69   }
70 
71   /* Called after handle_inferior_event decides the target is done
72      (that is, after stop_waiting).  The FSM is given a chance to
73      decide whether the command is done and thus the target should
74      stop, or whether there's still more to do and thus the thread
75      should be re-resumed.  This is a good place to cache target data
76      too.  For example, the "finish" command saves the just-finished
77      function's return value here.  */
78   virtual bool should_stop (struct thread_info *thread) = 0;
79 
80   /* If this FSM saved a function's return value, you can use this
81      method to retrieve it.  Otherwise, this returns NULL.  */
return_valuethread_fsm82   virtual struct return_value_info *return_value ()
83   {
84     return nullptr;
85   }
86 
async_reply_reasonthread_fsm87   enum async_reply_reason async_reply_reason ()
88   {
89     /* If we didn't finish, then the stop reason must come from
90        elsewhere.  E.g., a breakpoint hit or a signal intercepted.  */
91     gdb_assert (finished_p ());
92     return do_async_reply_reason ();
93   }
94 
95   /* Whether the stop should be notified to the user/frontend.  */
should_notify_stopthread_fsm96   virtual bool should_notify_stop ()
97   {
98     return true;
99   }
100 
set_finishedthread_fsm101   void set_finished ()
102   {
103     finished = true;
104   }
105 
finished_pthread_fsm106   bool finished_p () const
107   {
108     return finished;
109   }
110 
111   /* The interpreter that issued the execution command that caused
112      this thread to resume.  If the top level interpreter is MI/async,
113      and the execution command was a CLI command (next/step/etc.),
114      we'll want to print stop event output to the MI console channel
115      (the stepped-to line, etc.), as if the user entered the execution
116      command on a real GDB console.  */
117   struct interp *command_interp = nullptr;
118 
119 protected:
120 
121   /* Whether the FSM is done successfully.  */
122   bool finished = false;
123 
124   /* The async_reply_reason that is broadcast to MI clients if this
125      FSM finishes successfully.  */
do_async_reply_reasonthread_fsm126   virtual enum async_reply_reason do_async_reply_reason ()
127   {
128     gdb_assert_not_reached ("should not call async_reply_reason here");
129   }
130 };
131 
132 #endif /* THREAD_FSM_H */
133