contrib/llvm-project/lldb/include/lldb/Target/QueueItem.h

   1 //===-- QueueItem.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 #ifndef liblldb_QueueItem_h_
  10 #define liblldb_QueueItem_h_
  11
  12 #include <memory>
  13 #include <string>
  14 #include <vector>
  15
  16 #include "lldb/lldb-enumerations.h"
  17 #include "lldb/lldb-forward.h"
  18 #include "lldb/lldb-private.h"
  19
  20 #include "lldb/Core/Address.h"
  21 #include "lldb/Utility/ConstString.h"
  22
  23 namespace lldb_private {
  24
  25 // QueueItem:
  26 // This class represents a work item enqueued on a libdispatch aka Grand
  27 // Central Dispatch (GCD) queue.  Most often, this will be a function or block.
  28 // "enqueued" here means that the work item has been added to a queue but it
  29 // has not yet started executing.  When it is "dequeued", execution of the item
  30 // begins.
  31
  32 class QueueItem : public std::enable_shared_from_this<QueueItem> {
  33 public:
  34   QueueItem(lldb::QueueSP queue_sp, lldb::ProcessSP process_sp,
  35             lldb::addr_t item_ref, lldb_private::Address address);
  36
  37   ~QueueItem();
  38
  39   /// Get the kind of work item this is
  40   ///
  41   /// \return
  42   ///     The type of work item that this QueueItem object
  43   ///     represents.  eQueueItemKindUnknown may be returned.
  44   lldb::QueueItemKind GetKind();
  45
  46   /// Set the type of work item this is
  47   ///
  48   /// \param [in] item_kind
  49   ///     Set the kind of this work item object.
  50   void SetKind(lldb::QueueItemKind item_kind);
  51
  52   /// Get the code address that will be executed when this work item
  53   /// is executed.
  54   ///
  55   /// \return
  56   ///     The address that will be invoked when this work item is
  57   ///     executed.  Not all types of QueueItems will have an
  58   ///     address associated with them; check that the returned
  59   ///     Address is valid, or check that the WorkItemKind is a
  60   ///     kind that involves an address, such as eQueueItemKindFunction
  61   ///     or eQueueItemKindBlock.
  62   lldb_private::Address &GetAddress();
  63
  64   /// Set the work item address for this object
  65   ///
  66   /// \param [in] addr
  67   ///     The address that will be invoked when this work item
  68   ///     is executed.
  69   void SetAddress(lldb_private::Address addr);
  70
  71   /// Check if this QueueItem object is valid
  72   ///
  73   /// If the weak pointer to the parent Queue cannot be revivified,
  74   /// it is invalid.
  75   ///
  76   /// \return
  77   ///     True if this object is valid.
  78   bool IsValid() { return m_queue_wp.lock() != nullptr; }
  79
  80   /// Get an extended backtrace thread for this queue item, if available
  81   ///
  82   /// If the backtrace/thread information was collected when this item
  83   /// was enqueued, this call will provide it.
  84   ///
  85   /// \param [in] type
  86   ///     The type of extended backtrace being requested, e.g. "libdispatch"
  87   ///     or "pthread".
  88   ///
  89   /// \return
  90   ///     A thread shared pointer which will have a reference to an extended
  91   ///     thread if one was available.
  92   lldb::ThreadSP GetExtendedBacktraceThread(ConstString type);
  93
  94   void SetItemThatEnqueuedThis(lldb::addr_t address_of_item) {
  95     m_item_that_enqueued_this_ref = address_of_item;
  96   }
  97
  98   lldb::addr_t GetItemThatEnqueuedThis();
  99
 100   void SetEnqueueingThreadID(lldb::tid_t tid) { m_enqueueing_thread_id = tid; }
 101
 102   lldb::tid_t GetEnqueueingThreadID();
 103
 104   void SetEnqueueingQueueID(lldb::queue_id_t qid) {
 105     m_enqueueing_queue_id = qid;
 106   }
 107
 108   lldb::queue_id_t GetEnqueueingQueueID();
 109
 110   void SetTargetQueueID(lldb::queue_id_t qid) { m_target_queue_id = qid; }
 111
 112   void SetStopID(uint32_t stop_id) { m_stop_id = stop_id; }
 113
 114   uint32_t GetStopID();
 115
 116   void SetEnqueueingBacktrace(std::vector<lldb::addr_t> backtrace) {
 117     m_backtrace = backtrace;
 118   }
 119
 120   std::vector<lldb::addr_t> &GetEnqueueingBacktrace();
 121
 122   void SetThreadLabel(std::string thread_name) { m_thread_label = thread_name; }
 123
 124   std::string GetThreadLabel();
 125
 126   void SetQueueLabel(std::string queue_name) { m_queue_label = queue_name; }
 127
 128   std::string GetQueueLabel();
 129
 130   void SetTargetQueueLabel(std::string queue_name) {
 131     m_target_queue_label = queue_name;
 132   }
 133
 134   lldb::ProcessSP GetProcessSP();
 135
 136 protected:
 137   void FetchEntireItem();
 138
 139   lldb::QueueWP m_queue_wp;
 140   lldb::ProcessWP m_process_wp;
 141
 142   lldb::addr_t m_item_ref; // the token we can be used to fetch more information
 143                            // about this queue item
 144   lldb_private::Address m_address;
 145   bool m_have_fetched_entire_item;
 146
 147   lldb::QueueItemKind m_kind;
 148   lldb::addr_t m_item_that_enqueued_this_ref; // a handle that we can pass into
 149                                               // libBacktraceRecording
 150   // to get the QueueItem that enqueued this item
 151   lldb::tid_t m_enqueueing_thread_id; // thread that enqueued this item
 152   lldb::queue_id_t
 153       m_enqueueing_queue_id; // Queue that enqueued this item, if it was a queue
 154   lldb::queue_id_t m_target_queue_id;
 155   uint32_t m_stop_id; // indicates when this backtrace was recorded in time
 156   std::vector<lldb::addr_t> m_backtrace;
 157   std::string m_thread_label;
 158   std::string m_queue_label;
 159   std::string m_target_queue_label;
 160
 161 private:
 162   DISALLOW_COPY_AND_ASSIGN(QueueItem);
 163 };
 164
 165 } // namespace lldb_private
 166
 167 #endif // liblldb_QueueItem_h_