gdb/ui.h

   1 /* Copyright (C) 2023-2024 Free Software Foundation, Inc.
   2
   3    This file is part of GDB.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef UI_H
  19 #define UI_H
  20
  21 #include "gdbsupport/event-loop.h"
  22 #include "gdbsupport/intrusive_list.h"
  23 #include "gdbsupport/next-iterator.h"
  24
  25 struct interp;
  26
  27 /* Prompt state.  */
  28
  29 enum prompt_state
  30 {
  31   /* The command line is blocked simulating synchronous execution.
  32      This is used to implement the foreground execution commands
  33      ('run', 'continue', etc.).  We won't display the prompt and
  34      accept further commands until the execution is actually over.  */
  35   PROMPT_BLOCKED,
  36
  37   /* The command finished; display the prompt before returning back to
  38      the top level.  */
  39   PROMPT_NEEDED,
  40
  41   /* We've displayed the prompt already, ready for input.  */
  42   PROMPTED,
  43 };
  44
  45 /* All about a user interface instance.  Each user interface has its
  46    own I/O files/streams, readline state, its own top level
  47    interpreter (for the main UI, this is the interpreter specified
  48    with -i on the command line) and secondary interpreters (for
  49    interpreter-exec ...), etc.  There's always one UI associated with
  50    stdin/stdout/stderr, but the user can create secondary UIs, for
  51    example, to create a separate MI channel on its own stdio
  52    streams.  */
  53
  54 struct ui
  55 {
  56   /* Create a new UI.  */
  57   ui (FILE *instream, FILE *outstream, FILE *errstream);
  58   ~ui ();
  59
  60   DISABLE_COPY_AND_ASSIGN (ui);
  61
  62   /* Pointer to next in singly-linked list.  */
  63   struct ui *next = nullptr;
  64
  65   /* Convenient handle (UI number).  Unique across all UIs.  */
  66   int num;
  67
  68   /* The UI's command line buffer.  This is to used to accumulate
  69      input until we have a whole command line.  */
  70   std::string line_buffer;
  71
  72   /* The callback used by the event loop whenever an event is detected
  73      on the UI's input file descriptor.  This function incrementally
  74      builds a buffer where it accumulates the line read up to the
  75      point of invocation.  In the special case in which the character
  76      read is newline, the function invokes the INPUT_HANDLER callback
  77      (see below).  */
  78   void (*call_readline) (gdb_client_data) = nullptr;
  79
  80   /* The function to invoke when a complete line of input is ready for
  81      processing.  */
  82   void (*input_handler) (gdb::unique_xmalloc_ptr<char> &&) = nullptr;
  83
  84   /* True if this UI is using the readline library for command
  85      editing; false if using GDB's own simple readline emulation, with
  86      no editing support.  */
  87   int command_editing = 0;
  88
  89   /* Each UI has its own independent set of interpreters.  */
  90   intrusive_list<interp> interp_list;
  91   interp *current_interpreter = nullptr;
  92   interp *top_level_interpreter = nullptr;
  93
  94   /* The interpreter that is active while `interp_exec' is active, NULL
  95      at all other times.  */
  96   interp *command_interpreter = nullptr;
  97
  98   /* True if the UI is in async mode, false if in sync mode.  If in
  99      sync mode, a synchronous execution command (e.g, "next") does not
 100      return until the command is finished.  If in async mode, then
 101      running a synchronous command returns right after resuming the
 102      target.  Waiting for the command's completion is later done on
 103      the top event loop.  For the main UI, this starts out disabled,
 104      until all the explicit command line arguments (e.g., `gdb -ex
 105      "start" -ex "next"') are processed.  */
 106   int async = 0;
 107
 108   /* The number of nested readline secondary prompts that are
 109      currently active.  */
 110   int secondary_prompt_depth = 0;
 111
 112   /* The UI's stdin.  Set to stdin for the main UI.  */
 113   FILE *stdin_stream;
 114
 115   /* stdio stream that command input is being read from.  Set to stdin
 116      normally.  Set by source_command to the file we are sourcing.
 117      Set to NULL if we are executing a user-defined command or
 118      interacting via a GUI.  */
 119   FILE *instream;
 120   /* Standard output stream.  */
 121   FILE *outstream;
 122   /* Standard error stream.  */
 123   FILE *errstream;
 124
 125   /* The file descriptor for the input stream, so that we can register
 126      it with the event loop.  This can be set to -1 to prevent this
 127      registration.  */
 128   int input_fd;
 129
 130   /* Whether ISATTY returns true on input_fd.  Cached here because
 131      quit_force needs to know this _after_ input_fd might be
 132      closed.  */
 133   bool m_input_interactive_p;
 134
 135   /* See enum prompt_state's description.  */
 136   enum prompt_state prompt_state = PROMPT_NEEDED;
 137
 138   /* The fields below that start with "m_" are "private".  They're
 139      meant to be accessed through wrapper macros that make them look
 140      like globals.  */
 141
 142   /* The ui_file streams.  */
 143   /* Normal results */
 144   struct ui_file *m_gdb_stdout;
 145   /* Input stream */
 146   struct ui_file *m_gdb_stdin;
 147   /* Serious error notifications */
 148   struct ui_file *m_gdb_stderr;
 149   /* Log/debug/trace messages that should bypass normal stdout/stderr
 150      filtering.  */
 151   struct ui_file *m_gdb_stdlog;
 152
 153   /* The current ui_out.  */
 154   struct ui_out *m_current_uiout = nullptr;
 155
 156   /* Register the UI's input file descriptor in the event loop.  */
 157   void register_file_handler ();
 158
 159   /* Unregister the UI's input file descriptor from the event loop.  */
 160   void unregister_file_handler ();
 161
 162   /* Return true if this UI's input fd is a tty.  */
 163   bool input_interactive_p () const;
 164 };
 165
 166 /* The main UI.  This is the UI that is bound to stdin/stdout/stderr.
 167    It always exists and is created automatically when GDB starts
 168    up.  */
 169 extern struct ui *main_ui;
 170
 171 /* The current UI.  */
 172 extern struct ui *current_ui;
 173
 174 /* The list of all UIs.  */
 175 extern struct ui *ui_list;
 176
 177 /* State for SWITCH_THRU_ALL_UIS.  */
 178 class switch_thru_all_uis
 179 {
 180 public:
 181
 182   switch_thru_all_uis () : m_iter (ui_list), m_save_ui (&current_ui)
 183   {
 184     current_ui = ui_list;
 185   }
 186
 187   DISABLE_COPY_AND_ASSIGN (switch_thru_all_uis);
 188
 189   /* If done iterating, return true; otherwise return false.  */
 190   bool done () const
 191   {
 192     return m_iter == NULL;
 193   }
 194
 195   /* Move to the next UI, setting current_ui if iteration is not yet
 196      complete.  */
 197   void next ()
 198   {
 199     m_iter = m_iter->next;
 200     if (m_iter != NULL)
 201       current_ui = m_iter;
 202   }
 203
 204  private:
 205
 206   /* Used to iterate through the UIs.  */
 207   struct ui *m_iter;
 208
 209   /* Save and restore current_ui.  */
 210   scoped_restore_tmpl<struct ui *> m_save_ui;
 211 };
 212
 213   /* Traverse through all UI, and switch the current UI to the one
 214      being iterated.  */
 215 #define SWITCH_THRU_ALL_UIS()           \
 216   for (switch_thru_all_uis stau_state; !stau_state.done (); stau_state.next ())
 217
 218 using ui_range = next_range<ui>;
 219
 220 /* An adapter that can be used to traverse over all UIs.  */
 221 static inline
 222 ui_range all_uis ()
 223 {
 224   return ui_range (ui_list);
 225 }
 226
 227 #endif /* UI_H */