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