contrib/llvm/tools/lldb/include/lldb/Target/Queue.h

   1 //===-- Queue.h ------------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_Queue_h_
  11 #define liblldb_Queue_h_
  12
  13 #include <string>
  14 #include <vector>
  15
  16 #include "lldb/Target/QueueItem.h"
  17 #include "lldb/lldb-enumerations.h"
  18 #include "lldb/lldb-forward.h"
  19 #include "lldb/lldb-private.h"
  20
  21 namespace lldb_private {
  22
  23 //------------------------------------------------------------------
  24 // Queue:
  25 // This class represents a libdispatch aka Grand Central Dispatch queue in the
  26 // process.
  27 //
  28 // A program using libdispatch will create queues, put work items
  29 // (functions, blocks) on the queues.  The system will create / reassign
  30 // pthreads to execute the work items for the queues.  A serial queue will be
  31 // associated with a single thread (or possibly no thread, if it is not doing
  32 // any work).  A concurrent queue may be associated with multiple threads.
  33 //------------------------------------------------------------------
  34
  35 class Queue : public std::enable_shared_from_this<Queue> {
  36 public:
  37   Queue(lldb::ProcessSP process_sp, lldb::queue_id_t queue_id,
  38         const char *queue_name);
  39
  40   ~Queue();
  41
  42   //------------------------------------------------------------------
  43   /// Get the QueueID for this Queue
  44   ///
  45   /// A 64-bit ID number that uniquely identifies a queue at this particular
  46   /// stop_id.  Currently the libdispatch serialnum is used for the QueueID;
  47   /// it is a number that starts at 1 for each process and increments with
  48   /// each queue.  A serialnum is not reused for a different queue in the
  49   /// lifetime of that process execution.
  50   ///
  51   /// @return
  52   ///     The QueueID for this Queue.
  53   //------------------------------------------------------------------
  54   lldb::queue_id_t GetID();
  55
  56   //------------------------------------------------------------------
  57   /// Get the name of this Queue
  58   ///
  59   /// @return
  60   ///     The name of the queue, if one is available.
  61   ///     A NULL pointer is returned if none is available.
  62   //------------------------------------------------------------------
  63   const char *GetName();
  64
  65   //------------------------------------------------------------------
  66   /// Get the IndexID for this Queue
  67   ///
  68   /// This is currently the same as GetID().  If it changes in the future,
  69   /// it will be  a small integer value (starting with 1) assigned to
  70   /// each queue that is seen during a Process lifetime.
  71   ///
  72   /// Both the GetID and GetIndexID are being retained for Queues to
  73   /// maintain similar API to the Thread class, and allow for the
  74   /// possibility of GetID changing to a different source in the future.
  75   ///
  76   /// @return
  77   ///     The IndexID for this queue.
  78   //------------------------------------------------------------------
  79   uint32_t GetIndexID();
  80
  81   //------------------------------------------------------------------
  82   /// Return the threads currently associated with this queue
  83   ///
  84   /// Zero, one, or many threads may be executing code for a queue at
  85   /// a given point in time.  This call returns the list of threads
  86   /// that are currently executing work for this queue.
  87   ///
  88   /// @return
  89   ///     The threads currently performing work for this queue
  90   //------------------------------------------------------------------
  91   std::vector<lldb::ThreadSP> GetThreads();
  92
  93   //------------------------------------------------------------------
  94   /// Return the items that are currently enqueued
  95   ///
  96   /// "Enqueued" means that the item has been added to the queue to
  97   /// be done, but has not yet been done.  When the item is going to
  98   /// be processed it is "dequeued".
  99   ///
 100   /// @return
 101   ///     The vector of enqueued items for this queue
 102   //------------------------------------------------------------------
 103   const std::vector<lldb::QueueItemSP> &GetPendingItems();
 104
 105   lldb::ProcessSP GetProcess() const { return m_process_wp.lock(); }
 106
 107   //------------------------------------------------------------------
 108   /// Get the number of work items that this queue is currently running
 109   ///
 110   /// @return
 111   ///     The number of work items currently executing.  For a serial
 112   ///     queue, this will be 0 or 1.  For a concurrent queue, this
 113   ///     may be any number.
 114   //------------------------------------------------------------------
 115   uint32_t GetNumRunningWorkItems() const;
 116
 117   //------------------------------------------------------------------
 118   /// Get the number of work items enqueued on this queue
 119   ///
 120   /// @return
 121   ///     The number of work items currently enqueued, waiting to
 122   ///     execute.
 123   //------------------------------------------------------------------
 124   uint32_t GetNumPendingWorkItems() const;
 125
 126   //------------------------------------------------------------------
 127   /// Get the dispatch_queue_t structure address for this Queue
 128   ///
 129   /// Get the address in the inferior process' memory of this Queue's
 130   /// dispatch_queue_t structure.
 131   ///
 132   /// @return
 133   ///     The address of the dispatch_queue_t structure, if known.
 134   ///     LLDB_INVALID_ADDRESS will be returned if it is unavailable.
 135   //------------------------------------------------------------------
 136   lldb::addr_t GetLibdispatchQueueAddress() const;
 137
 138   void SetNumRunningWorkItems(uint32_t count);
 139
 140   void SetNumPendingWorkItems(uint32_t count);
 141
 142   void SetLibdispatchQueueAddress(lldb::addr_t dispatch_queue_t_addr);
 143
 144   void PushPendingQueueItem(lldb::QueueItemSP item) {
 145     m_pending_items.push_back(item);
 146   }
 147
 148   //------------------------------------------------------------------
 149   /// Return the kind (serial, concurrent) of this queue
 150   ///
 151   /// @return
 152   //      Whether this is a serial or a concurrent queue
 153   //------------------------------------------------------------------
 154   lldb::QueueKind GetKind();
 155
 156   void SetKind(lldb::QueueKind kind);
 157
 158 private:
 159   //------------------------------------------------------------------
 160   // For Queue only
 161   //------------------------------------------------------------------
 162
 163   lldb::ProcessWP m_process_wp;
 164   lldb::queue_id_t m_queue_id;
 165   std::string m_queue_name;
 166   uint32_t m_running_work_items_count;
 167   uint32_t m_pending_work_items_count;
 168   std::vector<lldb::QueueItemSP> m_pending_items;
 169   lldb::addr_t m_dispatch_queue_t_addr; // address of libdispatch
 170                                         // dispatch_queue_t for this Queue
 171   lldb::QueueKind m_kind;
 172
 173   DISALLOW_COPY_AND_ASSIGN(Queue);
 174 };
 175
 176 } // namespace lldb_private
 177
 178 #endif // liblldb_Queue_h_