LLDB  mainline
ScriptInterpreterPythonImpl.h
Go to the documentation of this file.
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"
17 
18 #include "lldb/Host/Terminal.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 
71  CreateSyntheticScriptedProvider(const char *class_name,
72  lldb::ValueObjectSP valobj) override;
73 
75  CreateScriptCommandObject(const char *class_name) override;
76 
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 
94  ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp,
95  bool &script_error) override;
96 
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 
109  CreateFrameRecognizer(const char *class_name) override;
110 
111  lldb::ValueObjectListSP
112  GetRecognizedArguments(const StructuredData::ObjectSP &implementor,
113  lldb::StackFrameSP frame_sp) override;
114 
116  OSPlugin_CreatePluginObject(const char *class_name,
117  lldb::ProcessSP process_sp) override;
118 
120  OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
121 
123  OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp) override;
124 
126  OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp,
127  lldb::tid_t thread_id) override;
128 
130  OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp,
131  lldb::tid_t tid, lldb::addr_t context) override;
132 
134  LoadPluginModule(const FileSpec &file_spec,
135  lldb_private::Status &error) override;
136 
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,
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,
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,
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_secondary_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
A class that represents a running process on the host machine.
std::shared_ptr< Array > ArraySP
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
std::shared_ptr< Dictionary > DictionarySP
uint64_t user_id_t
Definition: lldb-types.h:84
static llvm::raw_ostream & error(Stream &strm)
StateType
Process and Thread States.
uint64_t tid_t
Definition: lldb-types.h:86
static bool RunScriptFormatKeyword(Stream &s, const SymbolContext *sc, const ExecutionContext *exe_ctx, T t, const char *script_function_name)
static size_t CalculateNumChildren(CompilerType container_type, CompilerType element_type, lldb_private::ExecutionContextScope *exe_scope=nullptr)
Definition: VectorType.cpp:169
std::shared_ptr< String > StringSP
uint64_t addr_t
Definition: lldb-types.h:83
A uniqued constant string class.
Definition: ConstString.h:40
std::shared_ptr< Object > ObjectSP
std::shared_ptr< Generic > GenericSP
An error handling class.
Definition: Status.h:44