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 LLDB_TARGET_QUEUEITEM_H
10#define LLDB_TARGET_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
23namespace 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
32class QueueItem : public std::enable_shared_from_this<QueueItem> {
33public:
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
136protected:
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
161private:
162  QueueItem(const QueueItem &) = delete;
163  const QueueItem &operator=(const QueueItem &) = delete;
164};
165
166} // namespace lldb_private
167
168#endif // LLDB_TARGET_QUEUEITEM_H
169