Queue.h revision 269024 
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
22namespace 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
38class Queue :
39    public std::enable_shared_from_this<Queue>
40{
41public:
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
171private:
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_
190