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