contrib/llvm-project/lldb/source/Plugins/ScriptInterpreter/Python/ScriptInterpreterPythonImpl.h

   1 //===-- ScriptInterpreterPythonImpl.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 #include "lldb/Host/Config.h"
  10
  11 #if LLDB_ENABLE_PYTHON
  12
  13 #include "lldb-python.h"
  14
  15 #include "PythonDataObjects.h"
  16 #include "ScriptInterpreterPython.h"
  17
  18 #include "lldb/Host/Terminal.h"
  19 #include "lldb/Utility/StreamString.h"
  20
  21 #include "llvm/ADT/STLExtras.h"
  22 #include "llvm/ADT/StringRef.h"
  23
  24 namespace lldb_private {
  25 class IOHandlerPythonInterpreter;
  26 class ScriptInterpreterPythonImpl : public ScriptInterpreterPython {
  27 public:
  28   friend class IOHandlerPythonInterpreter;
  29
  30   ScriptInterpreterPythonImpl(Debugger &debugger);
  31
  32   ~ScriptInterpreterPythonImpl() override;
  33
  34   bool Interrupt() override;
  35
  36   bool ExecuteOneLine(
  37       llvm::StringRef command, CommandReturnObject *result,
  38       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
  39
  40   void ExecuteInterpreterLoop() override;
  41
  42   bool ExecuteOneLineWithReturn(
  43       llvm::StringRef in_string,
  44       ScriptInterpreter::ScriptReturnType return_type, void *ret_value,
  45       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
  46
  47   lldb_private::Status ExecuteMultipleLines(
  48       const char *in_string,
  49       const ExecuteScriptOptions &options = ExecuteScriptOptions()) override;
  50
  51   Status
  52   ExportFunctionDefinitionToInterpreter(StringList &function_def) override;
  53
  54   bool GenerateTypeScriptFunction(StringList &input, std::string &output,
  55                                   const void *name_token = nullptr) override;
  56
  57   bool GenerateTypeSynthClass(StringList &input, std::string &output,
  58                               const void *name_token = nullptr) override;
  59
  60   bool GenerateTypeSynthClass(const char *oneliner, std::string &output,
  61                               const void *name_token = nullptr) override;
  62
  63   // use this if the function code is just a one-liner script
  64   bool GenerateTypeScriptFunction(const char *oneliner, std::string &output,
  65                                   const void *name_token = nullptr) override;
  66
  67   bool GenerateScriptAliasFunction(StringList &input,
  68                                    std::string &output) override;
  69
  70   StructuredData::ObjectSP
  71   CreateSyntheticScriptedProvider(const char *class_name,
  72                                   lldb::ValueObjectSP valobj) override;
  73
  74   StructuredData::GenericSP
  75   CreateScriptCommandObject(const char *class_name) override;
  76
  77   StructuredData::ObjectSP
  78   CreateScriptedThreadPlan(const char *class_name,
  79                            StructuredDataImpl *args_data,
  80                            std::string &error_str,
  81                            lldb::ThreadPlanSP thread_plan) override;
  82
  83   bool ScriptedThreadPlanExplainsStop(StructuredData::ObjectSP implementor_sp,
  84                                       Event *event,
  85                                       bool &script_error) override;
  86
  87   bool ScriptedThreadPlanShouldStop(StructuredData::ObjectSP implementor_sp,
  88                                     Event *event, bool &script_error) override;
  89
  90   bool ScriptedThreadPlanIsStale(StructuredData::ObjectSP implementor_sp,
  91                                  bool &script_error) override;
  92
  93   lldb::StateType
  94   ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp,
  95                                 bool &script_error) override;
  96
  97   StructuredData::GenericSP
  98   CreateScriptedBreakpointResolver(const char *class_name,
  99                                    StructuredDataImpl *args_data,
 100                                    lldb::BreakpointSP &bkpt_sp) override;
 101   bool ScriptedBreakpointResolverSearchCallback(
 102       StructuredData::GenericSP implementor_sp,
 103       SymbolContext *sym_ctx) override;
 104
 105   lldb::SearchDepth ScriptedBreakpointResolverSearchDepth(
 106       StructuredData::GenericSP implementor_sp) override;
 107
 108   StructuredData::GenericSP
 109   CreateFrameRecognizer(const char *class_name) override;
 110
 111   lldb::ValueObjectListSP
 112   GetRecognizedArguments(const StructuredData::ObjectSP &implementor,
 113                          lldb::StackFrameSP frame_sp) override;
 114
 115   StructuredData::GenericSP
 116   OSPlugin_CreatePluginObject(const char *class_name,
 117                               lldb::ProcessSP process_sp) override;
 118
 119   StructuredData::DictionarySP
 120   OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
 121
 122   StructuredData::ArraySP
 123   OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
 124
 125   StructuredData::StringSP
 126   OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp,
 127                                lldb::tid_t thread_id) override;
 128
 129   StructuredData::DictionarySP
 130   OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp,
 131                         lldb::tid_t tid, lldb::addr_t context) override;
 132
 133   StructuredData::ObjectSP
 134   LoadPluginModule(const FileSpec &file_spec,
 135                    lldb_private::Status &error) override;
 136
 137   StructuredData::DictionarySP
 138   GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target,
 139                      const char *setting_name,
 140                      lldb_private::Status &error) override;
 141
 142   size_t CalculateNumChildren(const StructuredData::ObjectSP &implementor,
 143                               uint32_t max) override;
 144
 145   lldb::ValueObjectSP
 146   GetChildAtIndex(const StructuredData::ObjectSP &implementor,
 147                   uint32_t idx) override;
 148
 149   int GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor,
 150                               const char *child_name) override;
 151
 152   bool UpdateSynthProviderInstance(
 153       const StructuredData::ObjectSP &implementor) override;
 154
 155   bool MightHaveChildrenSynthProviderInstance(
 156       const StructuredData::ObjectSP &implementor) override;
 157
 158   lldb::ValueObjectSP
 159   GetSyntheticValue(const StructuredData::ObjectSP &implementor) override;
 160
 161   ConstString
 162   GetSyntheticTypeName(const StructuredData::ObjectSP &implementor) override;
 163
 164   bool
 165   RunScriptBasedCommand(const char *impl_function, llvm::StringRef args,
 166                         ScriptedCommandSynchronicity synchronicity,
 167                         lldb_private::CommandReturnObject &cmd_retobj,
 168                         Status &error,
 169                         const lldb_private::ExecutionContext &exe_ctx) override;
 170
 171   bool RunScriptBasedCommand(
 172       StructuredData::GenericSP impl_obj_sp, llvm::StringRef args,
 173       ScriptedCommandSynchronicity synchronicity,
 174       lldb_private::CommandReturnObject &cmd_retobj, Status &error,
 175       const lldb_private::ExecutionContext &exe_ctx) override;
 176
 177   Status GenerateFunction(const char *signature,
 178                           const StringList &input) override;
 179
 180   Status GenerateBreakpointCommandCallbackData(
 181       StringList &input,
 182       std::string &output,
 183       bool has_extra_args) override;
 184
 185   bool GenerateWatchpointCommandCallbackData(StringList &input,
 186                                              std::string &output) override;
 187
 188   bool GetScriptedSummary(const char *function_name, lldb::ValueObjectSP valobj,
 189                           StructuredData::ObjectSP &callee_wrapper_sp,
 190                           const TypeSummaryOptions &options,
 191                           std::string &retval) override;
 192
 193   bool GetDocumentationForItem(const char *item, std::string &dest) override;
 194
 195   bool GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
 196                                     std::string &dest) override;
 197
 198   uint32_t
 199   GetFlagsForCommandObject(StructuredData::GenericSP cmd_obj_sp) override;
 200
 201   bool GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp,
 202                                    std::string &dest) override;
 203
 204   bool CheckObjectExists(const char *name) override {
 205     if (!name || !name[0])
 206       return false;
 207     std::string temp;
 208     return GetDocumentationForItem(name, temp);
 209   }
 210
 211   bool RunScriptFormatKeyword(const char *impl_function, Process *process,
 212                               std::string &output, Status &error) override;
 213
 214   bool RunScriptFormatKeyword(const char *impl_function, Thread *thread,
 215                               std::string &output, Status &error) override;
 216
 217   bool RunScriptFormatKeyword(const char *impl_function, Target *target,
 218                               std::string &output, Status &error) override;
 219
 220   bool RunScriptFormatKeyword(const char *impl_function, StackFrame *frame,
 221                               std::string &output, Status &error) override;
 222
 223   bool RunScriptFormatKeyword(const char *impl_function, ValueObject *value,
 224                               std::string &output, Status &error) override;
 225
 226   bool
 227   LoadScriptingModule(const char *filename, bool init_session,
 228                       lldb_private::Status &error,
 229                       StructuredData::ObjectSP *module_sp = nullptr) override;
 230
 231   bool IsReservedWord(const char *word) override;
 232
 233   std::unique_ptr<ScriptInterpreterLocker> AcquireInterpreterLock() override;
 234
 235   void CollectDataForBreakpointCommandCallback(
 236       std::vector<BreakpointOptions *> &bp_options_vec,
 237       CommandReturnObject &result) override;
 238
 239   void
 240   CollectDataForWatchpointCommandCallback(WatchpointOptions *wp_options,
 241                                           CommandReturnObject &result) override;
 242
 243   /// Set the callback body text into the callback for the breakpoint.
 244   Status SetBreakpointCommandCallback(BreakpointOptions *bp_options,
 245                                       const char *callback_body) override;
 246
 247   Status SetBreakpointCommandCallbackFunction(
 248       BreakpointOptions *bp_options,
 249       const char *function_name,
 250       StructuredData::ObjectSP extra_args_sp) override;
 251
 252   /// This one is for deserialization:
 253   Status SetBreakpointCommandCallback(
 254       BreakpointOptions *bp_options,
 255       std::unique_ptr<BreakpointOptions::CommandData> &data_up) override;
 256
 257   Status SetBreakpointCommandCallback(BreakpointOptions *bp_options,
 258                                       const char *command_body_text,
 259                                       StructuredData::ObjectSP extra_args_sp,
 260                                       bool uses_extra_args);
 261
 262   /// Set a one-liner as the callback for the watchpoint.
 263   void SetWatchpointCommandCallback(WatchpointOptions *wp_options,
 264                                     const char *oneliner) override;
 265
 266   const char *GetDictionaryName() { return m_dictionary_name.c_str(); }
 267
 268   PyThreadState *GetThreadState() { return m_command_thread_state; }
 269
 270   void SetThreadState(PyThreadState *s) {
 271     if (s)
 272       m_command_thread_state = s;
 273   }
 274
 275   // IOHandlerDelegate
 276   void IOHandlerActivated(IOHandler &io_handler, bool interactive) override;
 277
 278   void IOHandlerInputComplete(IOHandler &io_handler,
 279                               std::string &data) override;
 280
 281   static lldb::ScriptInterpreterSP CreateInstance(Debugger &debugger);
 282
 283   // PluginInterface protocol
 284   lldb_private::ConstString GetPluginName() override;
 285
 286   uint32_t GetPluginVersion() override;
 287
 288   class Locker : public ScriptInterpreterLocker {
 289   public:
 290     enum OnEntry {
 291       AcquireLock = 0x0001,
 292       InitSession = 0x0002,
 293       InitGlobals = 0x0004,
 294       NoSTDIN = 0x0008
 295     };
 296
 297     enum OnLeave {
 298       FreeLock = 0x0001,
 299       FreeAcquiredLock = 0x0002, // do not free the lock if we already held it
 300                                  // when calling constructor
 301       TearDownSession = 0x0004
 302     };
 303
 304     Locker(ScriptInterpreterPythonImpl *py_interpreter,
 305            uint16_t on_entry = AcquireLock | InitSession,
 306            uint16_t on_leave = FreeLock | TearDownSession,
 307            lldb::FileSP in = nullptr, lldb::FileSP out = nullptr,
 308            lldb::FileSP err = nullptr);
 309
 310     ~Locker() override;
 311
 312   private:
 313     bool DoAcquireLock();
 314
 315     bool DoInitSession(uint16_t on_entry_flags, lldb::FileSP in,
 316                        lldb::FileSP out, lldb::FileSP err);
 317
 318     bool DoFreeLock();
 319
 320     bool DoTearDownSession();
 321
 322     bool m_teardown_session;
 323     ScriptInterpreterPythonImpl *m_python_interpreter;
 324     PyGILState_STATE m_GILState;
 325   };
 326
 327   static bool BreakpointCallbackFunction(void *baton,
 328                                          StoppointCallbackContext *context,
 329                                          lldb::user_id_t break_id,
 330                                          lldb::user_id_t break_loc_id);
 331   static bool WatchpointCallbackFunction(void *baton,
 332                                          StoppointCallbackContext *context,
 333                                          lldb::user_id_t watch_id);
 334   static void InitializePrivate();
 335
 336   class SynchronicityHandler {
 337   private:
 338     lldb::DebuggerSP m_debugger_sp;
 339     ScriptedCommandSynchronicity m_synch_wanted;
 340     bool m_old_asynch;
 341
 342   public:
 343     SynchronicityHandler(lldb::DebuggerSP, ScriptedCommandSynchronicity);
 344
 345     ~SynchronicityHandler();
 346   };
 347
 348   enum class AddLocation { Beginning, End };
 349
 350   static void AddToSysPath(AddLocation location, std::string path);
 351
 352   bool EnterSession(uint16_t on_entry_flags, lldb::FileSP in, lldb::FileSP out,
 353                     lldb::FileSP err);
 354
 355   void LeaveSession();
 356
 357   uint32_t IsExecutingPython() const { return m_lock_count > 0; }
 358
 359   uint32_t IncrementLockCount() { return ++m_lock_count; }
 360
 361   uint32_t DecrementLockCount() {
 362     if (m_lock_count > 0)
 363       --m_lock_count;
 364     return m_lock_count;
 365   }
 366
 367   enum ActiveIOHandler {
 368     eIOHandlerNone,
 369     eIOHandlerBreakpoint,
 370     eIOHandlerWatchpoint
 371   };
 372
 373   python::PythonModule &GetMainModule();
 374
 375   python::PythonDictionary &GetSessionDictionary();
 376
 377   python::PythonDictionary &GetSysModuleDictionary();
 378
 379   llvm::Expected<unsigned> GetMaxPositionalArgumentsForCallable(
 380       const llvm::StringRef &callable_name) override;
 381
 382   bool GetEmbeddedInterpreterModuleObjects();
 383
 384   bool SetStdHandle(lldb::FileSP file, const char *py_name,
 385                     python::PythonObject &save_file, const char *mode);
 386
 387   python::PythonObject m_saved_stdin;
 388   python::PythonObject m_saved_stdout;
 389   python::PythonObject m_saved_stderr;
 390   python::PythonModule m_main_module;
 391   python::PythonDictionary m_session_dict;
 392   python::PythonDictionary m_sys_module_dict;
 393   python::PythonObject m_run_one_line_function;
 394   python::PythonObject m_run_one_line_str_global;
 395   std::string m_dictionary_name;
 396   ActiveIOHandler m_active_io_handler;
 397   bool m_session_is_active;
 398   bool m_pty_slave_is_open;
 399   bool m_valid_session;
 400   uint32_t m_lock_count;
 401   PyThreadState *m_command_thread_state;
 402 };
 403
 404 class IOHandlerPythonInterpreter : public IOHandler {
 405 public:
 406   IOHandlerPythonInterpreter(Debugger &debugger,
 407                              ScriptInterpreterPythonImpl *python)
 408       : IOHandler(debugger, IOHandler::Type::PythonInterpreter),
 409         m_python(python) {}
 410
 411   ~IOHandlerPythonInterpreter() override {}
 412
 413   ConstString GetControlSequence(char ch) override {
 414     if (ch == 'd')
 415       return ConstString("quit()\n");
 416     return ConstString();
 417   }
 418
 419   void Run() override {
 420     if (m_python) {
 421       int stdin_fd = GetInputFD();
 422       if (stdin_fd >= 0) {
 423         Terminal terminal(stdin_fd);
 424         TerminalState terminal_state;
 425         const bool is_a_tty = terminal.IsATerminal();
 426
 427         if (is_a_tty) {
 428           terminal_state.Save(stdin_fd, false);
 429           terminal.SetCanonical(false);
 430           terminal.SetEcho(true);
 431         }
 432
 433         ScriptInterpreterPythonImpl::Locker locker(
 434             m_python,
 435             ScriptInterpreterPythonImpl::Locker::AcquireLock |
 436                 ScriptInterpreterPythonImpl::Locker::InitSession |
 437                 ScriptInterpreterPythonImpl::Locker::InitGlobals,
 438             ScriptInterpreterPythonImpl::Locker::FreeAcquiredLock |
 439                 ScriptInterpreterPythonImpl::Locker::TearDownSession);
 440
 441         // The following call drops into the embedded interpreter loop and
 442         // stays there until the user chooses to exit from the Python
 443         // interpreter. This embedded interpreter will, as any Python code that
 444         // performs I/O, unlock the GIL before a system call that can hang, and
 445         // lock it when the syscall has returned.
 446
 447         // We need to surround the call to the embedded interpreter with calls
 448         // to PyGILState_Ensure and PyGILState_Release (using the Locker
 449         // above). This is because Python has a global lock which must be held
 450         // whenever we want to touch any Python objects. Otherwise, if the user
 451         // calls Python code, the interpreter state will be off, and things
 452         // could hang (it's happened before).
 453
 454         StreamString run_string;
 455         run_string.Printf("run_python_interpreter (%s)",
 456                           m_python->GetDictionaryName());
 457         PyRun_SimpleString(run_string.GetData());
 458
 459         if (is_a_tty)
 460           terminal_state.Restore();
 461       }
 462     }
 463     SetIsDone(true);
 464   }
 465
 466   void Cancel() override {}
 467
 468   bool Interrupt() override { return m_python->Interrupt(); }
 469
 470   void GotEOF() override {}
 471
 472 protected:
 473   ScriptInterpreterPythonImpl *m_python;
 474 };
 475
 476 } // namespace lldb_private
 477
 478 #endif