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