diff options
Diffstat (limited to 'include/lldb/Target/SystemRuntime.h')
| -rw-r--r-- | include/lldb/Target/SystemRuntime.h | 134 |
1 files changed, 63 insertions, 71 deletions
diff --git a/include/lldb/Target/SystemRuntime.h b/include/lldb/Target/SystemRuntime.h index 8c6c2ece967f..06cc3ec2d012 100644 --- a/include/lldb/Target/SystemRuntime.h +++ b/include/lldb/Target/SystemRuntime.h @@ -29,20 +29,20 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h" -/// @brief A plug-in interface definition class for system runtimes. +/// A plug-in interface definition class for system runtimes. /// /// The system runtime plugins can collect information from the system -/// libraries during a Process' lifetime and provide information about -/// how objects/threads were originated. +/// libraries during a Process' lifetime and provide information about how +/// objects/threads were originated. /// -/// For instance, a system runtime plugin use a breakpoint when threads -/// are created to record the backtrace of where that thread was created. -/// Later, when backtracing the created thread, it could extend the backtrace -/// to show where it was originally created from. +/// For instance, a system runtime plugin use a breakpoint when threads are +/// created to record the backtrace of where that thread was created. Later, +/// when backtracing the created thread, it could extend the backtrace to show +/// where it was originally created from. /// -/// The plugin will insert its own breakpoint when Created and start collecting -/// information. Later when it comes time to augment a Thread, it can be -/// asked to provide that information. +/// The plugin will insert its own breakpoint when Created and start +/// collecting information. Later when it comes time to augment a Thread, it +/// can be asked to provide that information. /// //---------------------------------------------------------------------- @@ -51,9 +51,8 @@ public: //------------------------------------------------------------------ /// Find a system runtime plugin for a given process. /// - /// Scans the installed SystemRuntime plugins and tries to find - /// an instance that can be used to track image changes in \a - /// process. + /// Scans the installed SystemRuntime plugins and tries to find an instance + /// that can be used to track image changes in \a process. /// /// @param[in] process /// The process for which to try and locate a system runtime @@ -69,60 +68,60 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// by the plug-in instance. //------------------------------------------------------------------ ~SystemRuntime() override; //------------------------------------------------------------------ /// Called after attaching to a process. /// - /// Allow the SystemRuntime plugin to execute some code after attaching - /// to a process. + /// Allow the SystemRuntime plugin to execute some code after attaching to a + /// process. //------------------------------------------------------------------ virtual void DidAttach(); //------------------------------------------------------------------ /// Called after launching a process. /// - /// Allow the SystemRuntime plugin to execute some code after launching - /// a process. + /// Allow the SystemRuntime plugin to execute some code after launching a + /// process. //------------------------------------------------------------------ virtual void DidLaunch(); //------------------------------------------------------------------ /// Called when modules have been loaded in the process. /// - /// Allow the SystemRuntime plugin to enable logging features in the - /// system runtime libraries. + /// Allow the SystemRuntime plugin to enable logging features in the system + /// runtime libraries. //------------------------------------------------------------------ virtual void ModulesDidLoad(lldb_private::ModuleList &module_list); //------------------------------------------------------------------ /// Called before detaching from a process. /// - /// This will give a SystemRuntime plugin a chance to free any resources - /// in the inferior process before we detach. + /// This will give a SystemRuntime plugin a chance to free any resources in + /// the inferior process before we detach. //------------------------------------------------------------------ virtual void Detach(); //------------------------------------------------------------------ - /// Return a list of thread origin extended backtraces that may - /// be available. + /// Return a list of thread origin extended backtraces that may be + /// available. /// /// A System Runtime may be able to provide a backtrace of when this - /// thread was originally created. Furthermore, it may be able to - /// provide that extended backtrace for different styles of creation. - /// On a system with both pthreads and libdispatch, aka Grand Central - /// Dispatch, queues, the system runtime may be able to provide the - /// pthread creation of the thread and it may also be able to provide - /// the backtrace of when this GCD queue work block was enqueued. - /// The caller may request these different origins by name. + /// thread was originally created. Furthermore, it may be able to provide + /// that extended backtrace for different styles of creation. On a system + /// with both pthreads and libdispatch, aka Grand Central Dispatch, queues, + /// the system runtime may be able to provide the pthread creation of the + /// thread and it may also be able to provide the backtrace of when this GCD + /// queue work block was enqueued. The caller may request these different + /// origins by name. /// - /// The names will be provided in the order that they are most likely - /// to be requested. For instance, a most natural order may be to - /// request the GCD libdispatch queue origin. If there is none, then - /// request the pthread origin. + /// The names will be provided in the order that they are most likely to be + /// requested. For instance, a most natural order may be to request the GCD + /// libdispatch queue origin. If there is none, then request the pthread + /// origin. /// /// @return /// A vector of ConstStrings with names like "pthread" or "libdispatch". @@ -135,13 +134,12 @@ public: /// Return a Thread which shows the origin of this thread's creation. /// /// This likely returns a HistoryThread which shows how thread was - /// originally created (e.g. "pthread" type), or how the work that - /// is currently executing on it was originally enqueued (e.g. - /// "libdispatch" type). + /// originally created (e.g. "pthread" type), or how the work that is + /// currently executing on it was originally enqueued (e.g. "libdispatch" + /// type). /// - /// There may be a chain of thread-origins; it may be informative to - /// the end user to query the returned ThreadSP for its origins as - /// well. + /// There may be a chain of thread-origins; it may be informative to the end + /// user to query the returned ThreadSP for its origins as well. /// /// @param [in] thread /// The thread to examine. @@ -168,8 +166,8 @@ public: /// a libdispatch queue in the future, or it represents a function/block /// that is currently executing on a thread. /// - /// This method will report a thread backtrace of the function that - /// enqueued it originally, if possible. + /// This method will report a thread backtrace of the function that enqueued + /// it originally, if possible. /// /// @param [in] queue_item_sp /// The QueueItem that we are getting an extended backtrace for. @@ -189,10 +187,11 @@ public: } //------------------------------------------------------------------ - /// Populate the Process' QueueList with libdispatch / GCD queues that exist. + /// Populate the Process' QueueList with libdispatch / GCD queues that + /// exist. /// - /// When process execution is paused, the SystemRuntime may be called to fill - /// in the list of Queues that currently exist. + /// When process execution is paused, the SystemRuntime may be called to + /// fill in the list of Queues that currently exist. /// /// @param [out] queue_list /// This QueueList will be cleared, and any queues that currently exist @@ -205,12 +204,10 @@ public: /// Get the queue name for a thread given a thread's dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. At the - /// dispatch_qaddr - /// we will find the address of this thread's dispatch_queue_t structure. - /// Given the address of the dispatch_queue_t structure for a thread, - /// get the queue name and return it. + /// queue. There will be a call to get the thread's dispatch_qaddr. At the + /// dispatch_qaddr we will find the address of this thread's + /// dispatch_queue_t structure. Given the address of the dispatch_queue_t + /// structure for a thread, get the queue name and return it. /// /// @param [in] dispatch_qaddr /// The address of the dispatch_qaddr pointer for this thread. @@ -229,12 +226,10 @@ public: /// dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. At the - /// dispatch_qaddr - /// we will find the address of this thread's dispatch_queue_t structure. - /// Given the address of the dispatch_queue_t structure for a thread, - /// get the queue ID and return it. + /// queue. There will be a call to get the thread's dispatch_qaddr. At the + /// dispatch_qaddr we will find the address of this thread's + /// dispatch_queue_t structure. Given the address of the dispatch_queue_t + /// structure for a thread, get the queue ID and return it. /// /// @param [in] dispatch_qaddr /// The address of the dispatch_qaddr pointer for this thread. @@ -252,10 +247,8 @@ public: /// dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. - /// Given the thread's dispatch_qaddr, find the libdispatch_queue_t address - /// and + /// queue. There will be a call to get the thread's dispatch_qaddr. Given + /// the thread's dispatch_qaddr, find the libdispatch_queue_t address and /// return it. /// /// @param [in] dispatch_qaddr @@ -274,8 +267,8 @@ public: /// Retrieve the Queue kind for the queue at a thread's dispatch_qaddr. /// /// Retrieve the Queue kind - either eQueueKindSerial or - /// eQueueKindConcurrent, indicating that this queue processes work - /// items serially or concurrently. + /// eQueueKindConcurrent, indicating that this queue processes work items + /// serially or concurrently. /// /// @return /// The Queue kind, if it could be read, else eQueueKindUnknown. @@ -288,8 +281,8 @@ public: /// Get the pending work items for a libdispatch Queue /// /// If this system/process is using libdispatch and the runtime can do so, - /// retrieve the list of pending work items for the specified Queue and - /// add it to the Queue. + /// retrieve the list of pending work items for the specified Queue and add + /// it to the Queue. /// /// @param [in] queue /// The queue of interest. @@ -300,8 +293,8 @@ public: /// Complete the fields in a QueueItem /// /// PopulatePendingItemsForQueue() may not fill in all of the QueueItem - /// details; when the remaining fields are needed, they will be - /// fetched by call this method. + /// details; when the remaining fields are needed, they will be fetched by + /// call this method. /// /// @param [in] queue_item /// The QueueItem that we will be completing. @@ -316,8 +309,7 @@ public: //------------------------------------------------------------------ /// Add key-value pairs to the StructuredData dictionary object with /// information debugserver may need when constructing the - /// jThreadExtendedInfo - /// packet. + /// jThreadExtendedInfo packet. /// /// @param [out] dict /// Dictionary to which key-value pairs should be added; they will |