1 | //===-- Broadcaster.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_UTILITY_BROADCASTER_H |
10 | #define LLDB_UTILITY_BROADCASTER_H |
11 | |
12 | #include "lldb/Utility/ConstString.h" |
13 | #include "lldb/lldb-defines.h" |
14 | #include "lldb/lldb-forward.h" |
15 | |
16 | #include "llvm/ADT/SmallVector.h" |
17 | |
18 | #include <cstdint> |
19 | #include <map> |
20 | #include <memory> |
21 | #include <mutex> |
22 | #include <set> |
23 | #include <string> |
24 | #include <utility> |
25 | #include <vector> |
26 | |
27 | namespace lldb_private { |
28 | class Broadcaster; |
29 | class EventData; |
30 | class Listener; |
31 | class Stream; |
32 | } // namespace lldb_private |
33 | |
34 | namespace lldb_private { |
35 | |
36 | /// lldb::BroadcastEventSpec |
37 | /// |
38 | /// This class is used to specify a kind of event to register for. The |
39 | /// Debugger maintains a list of BroadcastEventSpec's and when it is made |
40 | class BroadcastEventSpec { |
41 | public: |
42 | BroadcastEventSpec(const ConstString &broadcaster_class, uint32_t event_bits) |
43 | : m_broadcaster_class(broadcaster_class), m_event_bits(event_bits) {} |
44 | |
45 | ~BroadcastEventSpec() = default; |
46 | |
47 | ConstString GetBroadcasterClass() const { return m_broadcaster_class; } |
48 | |
49 | uint32_t GetEventBits() const { return m_event_bits; } |
50 | |
51 | /// Tell whether this BroadcastEventSpec is contained in in_spec. That is: |
52 | /// (a) the two spec's share the same broadcaster class (b) the event bits of |
53 | /// this spec are wholly contained in those of in_spec. |
54 | bool IsContainedIn(const BroadcastEventSpec &in_spec) const { |
55 | if (m_broadcaster_class != in_spec.GetBroadcasterClass()) |
56 | return false; |
57 | uint32_t in_bits = in_spec.GetEventBits(); |
58 | if (in_bits == m_event_bits) |
59 | return true; |
60 | |
61 | if ((m_event_bits & in_bits) != 0 && (m_event_bits & ~in_bits) == 0) |
62 | return true; |
63 | |
64 | return false; |
65 | } |
66 | |
67 | bool operator<(const BroadcastEventSpec &rhs) const; |
68 | |
69 | private: |
70 | ConstString m_broadcaster_class; |
71 | uint32_t m_event_bits; |
72 | }; |
73 | |
74 | class BroadcasterManager |
75 | : public std::enable_shared_from_this<BroadcasterManager> { |
76 | public: |
77 | friend class Listener; |
78 | |
79 | protected: |
80 | BroadcasterManager(); |
81 | |
82 | public: |
83 | /// Listeners hold onto weak pointers to their broadcaster managers. So they |
84 | /// must be made into shared pointers, which you do with |
85 | /// MakeBroadcasterManager. |
86 | static lldb::BroadcasterManagerSP MakeBroadcasterManager(); |
87 | |
88 | ~BroadcasterManager() = default; |
89 | |
90 | uint32_t RegisterListenerForEvents(const lldb::ListenerSP &listener_sp, |
91 | const BroadcastEventSpec &event_spec); |
92 | |
93 | bool UnregisterListenerForEvents(const lldb::ListenerSP &listener_sp, |
94 | const BroadcastEventSpec &event_spec); |
95 | |
96 | lldb::ListenerSP |
97 | GetListenerForEventSpec(const BroadcastEventSpec &event_spec) const; |
98 | |
99 | void SignUpListenersForBroadcaster(Broadcaster &broadcaster); |
100 | |
101 | void RemoveListener(const lldb::ListenerSP &listener_sp); |
102 | |
103 | void RemoveListener(Listener *listener); |
104 | |
105 | void Clear(); |
106 | |
107 | private: |
108 | typedef std::pair<BroadcastEventSpec, lldb::ListenerSP> event_listener_key; |
109 | typedef std::map<BroadcastEventSpec, lldb::ListenerSP> collection; |
110 | typedef std::set<lldb::ListenerSP> listener_collection; |
111 | collection m_event_map; |
112 | listener_collection m_listeners; |
113 | |
114 | mutable std::recursive_mutex m_manager_mutex; |
115 | }; |
116 | |
117 | /// \class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event |
118 | /// broadcasting class. |
119 | /// |
120 | /// The Broadcaster class is designed to be subclassed by objects that wish to |
121 | /// vend events in a multi-threaded environment. Broadcaster objects can each |
122 | /// vend 32 events. Each event is represented by a bit in a 32 bit value and |
123 | /// these bits can be set: |
124 | /// \see Broadcaster::SetEventBits(uint32_t) |
125 | /// or cleared: |
126 | /// \see Broadcaster::ResetEventBits(uint32_t) |
127 | /// When an event gets set the Broadcaster object will notify the Listener |
128 | /// object that is listening for the event (if there is one). |
129 | /// |
130 | /// Subclasses should provide broadcast bit definitions for any events they |
131 | /// vend, typically using an enumeration: |
132 | /// \code |
133 | /// class Foo : public Broadcaster |
134 | /// { |
135 | /// public: |
136 | /// // Broadcaster event bits definitions. |
137 | /// enum |
138 | /// { |
139 | /// eBroadcastBitOne = (1 << 0), |
140 | /// eBroadcastBitTwo = (1 << 1), |
141 | /// eBroadcastBitThree = (1 << 2), |
142 | /// ... |
143 | /// }; |
144 | /// \endcode |
145 | class Broadcaster { |
146 | friend class Listener; |
147 | friend class Event; |
148 | |
149 | public: |
150 | /// Construct with a broadcaster with a name. |
151 | /// |
152 | /// \param[in] manager_sp |
153 | /// A shared pointer to the BroadcasterManager that will manage this |
154 | /// broadcaster. |
155 | /// \param[in] name |
156 | /// A std::string of the name that this broadcaster will have. |
157 | Broadcaster(lldb::BroadcasterManagerSP manager_sp, std::string name); |
158 | |
159 | /// Destructor. |
160 | /// |
161 | /// The destructor is virtual since this class gets subclassed. |
162 | virtual ~Broadcaster(); |
163 | |
164 | void CheckInWithManager(); |
165 | |
166 | /// Broadcast an event which has no associated data. |
167 | void BroadcastEvent(lldb::EventSP &event_sp) { |
168 | m_broadcaster_sp->BroadcastEvent(event_sp); |
169 | } |
170 | |
171 | void BroadcastEventIfUnique(lldb::EventSP &event_sp) { |
172 | m_broadcaster_sp->BroadcastEventIfUnique(event_sp); |
173 | } |
174 | |
175 | void BroadcastEvent(uint32_t event_type, |
176 | const lldb::EventDataSP &event_data_sp) { |
177 | m_broadcaster_sp->BroadcastEvent(event_type, event_data_sp); |
178 | } |
179 | |
180 | void BroadcastEvent(uint32_t event_type) { |
181 | m_broadcaster_sp->BroadcastEvent(event_type); |
182 | } |
183 | |
184 | void BroadcastEventIfUnique(uint32_t event_type) { |
185 | m_broadcaster_sp->BroadcastEventIfUnique(event_type); |
186 | } |
187 | |
188 | void Clear() { m_broadcaster_sp->Clear(); } |
189 | |
190 | virtual void AddInitialEventsToListener(const lldb::ListenerSP &listener_sp, |
191 | uint32_t requested_events); |
192 | |
193 | /// Listen for any events specified by \a event_mask. |
194 | /// |
195 | /// Only one listener can listen to each event bit in a given Broadcaster. |
196 | /// Once a listener has acquired an event bit, no other broadcaster will |
197 | /// have access to it until it is relinquished by the first listener that |
198 | /// gets it. The actual event bits that get acquired by \a listener may be |
199 | /// different from what is requested in \a event_mask, and to track this the |
200 | /// actual event bits that are acquired get returned. |
201 | /// |
202 | /// \param[in] listener_sp |
203 | /// The Listener object that wants to monitor the events that |
204 | /// get broadcast by this object. |
205 | /// |
206 | /// \param[in] event_mask |
207 | /// A bit mask that indicates which events the listener is |
208 | /// asking to monitor. |
209 | /// |
210 | /// \return |
211 | /// The actual event bits that were acquired by \a listener. |
212 | uint32_t AddListener(const lldb::ListenerSP &listener_sp, |
213 | uint32_t event_mask) { |
214 | return m_broadcaster_sp->AddListener(listener_sp, event_mask); |
215 | } |
216 | |
217 | /// Get this broadcaster's name. |
218 | /// |
219 | /// \return |
220 | /// A reference to a constant std::string containing the name of the |
221 | /// broadcaster. |
222 | const std::string &GetBroadcasterName() { return m_broadcaster_name; } |
223 | |
224 | /// Get the event name(s) for one or more event bits. |
225 | /// |
226 | /// \param[in] event_mask |
227 | /// A bit mask that indicates which events to get names for. |
228 | /// |
229 | /// \return |
230 | /// The NULL terminated C string name of this Broadcaster. |
231 | bool GetEventNames(Stream &s, const uint32_t event_mask, |
232 | bool prefix_with_broadcaster_name) const { |
233 | return m_broadcaster_sp->GetEventNames(s, event_mask, |
234 | prefix_with_broadcaster_name); |
235 | } |
236 | |
237 | /// Set the name for an event bit. |
238 | /// |
239 | /// \param[in] event_mask |
240 | /// A bit mask that indicates which events the listener is |
241 | /// asking to monitor. |
242 | void SetEventName(uint32_t event_mask, const char *name) { |
243 | m_broadcaster_sp->SetEventName(event_mask, name); |
244 | } |
245 | |
246 | const char *GetEventName(uint32_t event_mask) const { |
247 | return m_broadcaster_sp->GetEventName(event_mask); |
248 | } |
249 | |
250 | bool EventTypeHasListeners(uint32_t event_type) { |
251 | return m_broadcaster_sp->EventTypeHasListeners(event_type); |
252 | } |
253 | |
254 | /// Removes a Listener from this broadcasters list and frees the event bits |
255 | /// specified by \a event_mask that were previously acquired by \a listener |
256 | /// (assuming \a listener was listening to this object) for other listener |
257 | /// objects to use. |
258 | /// |
259 | /// \param[in] listener_sp |
260 | /// A Listener object that previously called AddListener. |
261 | /// |
262 | /// \param[in] event_mask |
263 | /// The event bits \a listener wishes to relinquish. |
264 | /// |
265 | /// \return |
266 | /// \b True if the listener was listening to this broadcaster |
267 | /// and was removed, \b false otherwise. |
268 | /// |
269 | /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t) |
270 | bool RemoveListener(const lldb::ListenerSP &listener_sp, |
271 | uint32_t event_mask = UINT32_MAX) { |
272 | return m_broadcaster_sp->RemoveListener(listener_sp, event_mask); |
273 | } |
274 | |
275 | /// Provides a simple mechanism to temporarily redirect events from |
276 | /// broadcaster. When you call this function passing in a listener and |
277 | /// event type mask, all events from the broadcaster matching the mask will |
278 | /// now go to the hijacking listener. Only one hijack can occur at a time. |
279 | /// If we need more than this we will have to implement a Listener stack. |
280 | /// |
281 | /// \param[in] listener_sp |
282 | /// A Listener object. You do not need to call StartListeningForEvents |
283 | /// for this broadcaster (that would fail anyway since the event bits |
284 | /// would most likely be taken by the listener(s) you are usurping. |
285 | /// |
286 | /// \param[in] event_mask |
287 | /// The event bits \a listener wishes to hijack. |
288 | /// |
289 | /// \return |
290 | /// \b True if the event mask could be hijacked, \b false otherwise. |
291 | /// |
292 | /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t) |
293 | bool HijackBroadcaster(const lldb::ListenerSP &listener_sp, |
294 | uint32_t event_mask = UINT32_MAX) { |
295 | return m_broadcaster_sp->HijackBroadcaster(listener_sp, event_mask); |
296 | } |
297 | |
298 | bool IsHijackedForEvent(uint32_t event_mask) { |
299 | return m_broadcaster_sp->IsHijackedForEvent(event_mask); |
300 | } |
301 | |
302 | /// Restore the state of the Broadcaster from a previous hijack attempt. |
303 | void RestoreBroadcaster() { m_broadcaster_sp->RestoreBroadcaster(); } |
304 | |
305 | /// This needs to be filled in if you are going to register the broadcaster |
306 | /// with the broadcaster manager and do broadcaster class matching. |
307 | /// FIXME: Probably should make a ManagedBroadcaster subclass with all the |
308 | /// bits needed to work with the BroadcasterManager, so that it is clearer |
309 | /// how to add one. |
310 | virtual ConstString &GetBroadcasterClass() const; |
311 | |
312 | lldb::BroadcasterManagerSP GetManager(); |
313 | |
314 | void SetPrimaryListener(lldb::ListenerSP listener_sp) { |
315 | m_broadcaster_sp->SetPrimaryListener(listener_sp); |
316 | } |
317 | |
318 | lldb::ListenerSP GetPrimaryListener() { |
319 | return m_broadcaster_sp->m_primary_listener_sp; |
320 | } |
321 | |
322 | protected: |
323 | /// BroadcasterImpl contains the actual Broadcaster implementation. The |
324 | /// Broadcaster makes a BroadcasterImpl which lives as long as it does. The |
325 | /// Listeners & the Events hold a weak pointer to the BroadcasterImpl, so |
326 | /// that they can survive if a Broadcaster they were listening to is |
327 | /// destroyed w/o their being able to unregister from it (which can happen if |
328 | /// the Broadcasters & Listeners are being destroyed on separate threads |
329 | /// simultaneously. The Broadcaster itself can't be shared out as a weak |
330 | /// pointer, because some things that are broadcasters (e.g. the Target and |
331 | /// the Process) are shared in their own right. |
332 | /// |
333 | /// For the most part, the Broadcaster functions dispatch to the |
334 | /// BroadcasterImpl, and are documented in the public Broadcaster API above. |
335 | class BroadcasterImpl { |
336 | friend class Listener; |
337 | friend class Broadcaster; |
338 | |
339 | public: |
340 | BroadcasterImpl(Broadcaster &broadcaster); |
341 | |
342 | ~BroadcasterImpl() = default; |
343 | |
344 | void BroadcastEvent(lldb::EventSP &event_sp); |
345 | |
346 | void BroadcastEventIfUnique(lldb::EventSP &event_sp); |
347 | |
348 | void BroadcastEvent(uint32_t event_type); |
349 | |
350 | void BroadcastEvent(uint32_t event_type, |
351 | const lldb::EventDataSP &event_data_sp); |
352 | |
353 | void BroadcastEventIfUnique(uint32_t event_type); |
354 | |
355 | void Clear(); |
356 | |
357 | uint32_t AddListener(const lldb::ListenerSP &listener_sp, |
358 | uint32_t event_mask); |
359 | |
360 | const std::string &GetBroadcasterName() const { |
361 | return m_broadcaster.GetBroadcasterName(); |
362 | } |
363 | |
364 | Broadcaster *GetBroadcaster(); |
365 | |
366 | bool GetEventNames(Stream &s, const uint32_t event_mask, |
367 | bool prefix_with_broadcaster_name) const; |
368 | |
369 | void SetEventName(uint32_t event_mask, const char *name) { |
370 | m_event_names[event_mask] = name; |
371 | } |
372 | |
373 | const char *GetEventName(uint32_t event_mask) const { |
374 | const auto pos = m_event_names.find(x: event_mask); |
375 | if (pos != m_event_names.end()) |
376 | return pos->second.c_str(); |
377 | return nullptr; |
378 | } |
379 | |
380 | bool EventTypeHasListeners(uint32_t event_type); |
381 | |
382 | void SetPrimaryListener(lldb::ListenerSP listener_sp); |
383 | |
384 | bool RemoveListener(lldb_private::Listener *listener, |
385 | uint32_t event_mask = UINT32_MAX); |
386 | |
387 | bool RemoveListener(const lldb::ListenerSP &listener_sp, |
388 | uint32_t event_mask = UINT32_MAX); |
389 | |
390 | bool HijackBroadcaster(const lldb::ListenerSP &listener_sp, |
391 | uint32_t event_mask = UINT32_MAX); |
392 | |
393 | bool IsHijackedForEvent(uint32_t event_mask); |
394 | |
395 | void RestoreBroadcaster(); |
396 | |
397 | protected: |
398 | void PrivateBroadcastEvent(lldb::EventSP &event_sp, bool unique); |
399 | |
400 | const char *GetHijackingListenerName(); |
401 | |
402 | typedef llvm::SmallVector<std::pair<lldb::ListenerWP, uint32_t>, 4> |
403 | collection; |
404 | typedef std::map<uint32_t, std::string> event_names_map; |
405 | |
406 | llvm::SmallVector<std::pair<lldb::ListenerSP, uint32_t &>, 4> |
407 | GetListeners(uint32_t event_mask = UINT32_MAX, bool include_primary = true); |
408 | |
409 | bool HasListeners(uint32_t event_mask); |
410 | |
411 | /// The broadcaster that this implements. |
412 | Broadcaster &m_broadcaster; |
413 | |
414 | /// Optionally define event names for readability and logging for each |
415 | /// event bit. |
416 | event_names_map m_event_names; |
417 | |
418 | /// A Broadcaster can have zero, one or many listeners. A Broadcaster with |
419 | /// zero listeners is a no-op, with one Listener is trivial. |
420 | /// In most cases of multiple Listeners,the Broadcaster treats all its |
421 | /// Listeners as equal, sending each event to all of the Listeners in no |
422 | /// guaranteed order. |
423 | /// However, some Broadcasters - in particular the Process broadcaster, can |
424 | /// designate one Listener to be the "Primary Listener". In the case of |
425 | /// the Process Broadcaster, the Listener passed to the Process constructor |
426 | /// will be the Primary Listener. |
427 | /// If the broadcaster has a Primary Listener, then the event gets |
428 | /// sent first to the Primary Listener, and then when the Primary Listener |
429 | /// pulls the event and the the event's DoOnRemoval finishes running, |
430 | /// the event is forwarded to all the other Listeners. |
431 | /// The other wrinkle is that a Broadcaster may be serving a Hijack |
432 | /// Listener. If the Hijack Listener is present, events are only sent to |
433 | /// the Hijack Listener. We use that, for instance, to absorb all the |
434 | /// events generated by running an expression so that they don't show up to |
435 | /// the driver or UI as starts and stops. |
436 | /// If a Broadcaster has both a Primary and a Hijack Listener, the top-most |
437 | /// Hijack Listener is treated as the current Primary Listener. |
438 | |
439 | /// A list of Listener / event_mask pairs that are listening to this |
440 | /// broadcaster. |
441 | collection m_listeners; |
442 | |
443 | /// A mutex that protects \a m_listeners. |
444 | std::recursive_mutex m_listeners_mutex; |
445 | |
446 | /// See the discussion of Broadcasters and Listeners above. |
447 | lldb::ListenerSP m_primary_listener_sp; |
448 | // The primary listener listens to all bits: |
449 | uint32_t m_primary_listener_mask = UINT32_MAX; |
450 | |
451 | /// A simple mechanism to intercept events from a broadcaster |
452 | std::vector<lldb::ListenerSP> m_hijacking_listeners; |
453 | |
454 | /// At some point we may want to have a stack or Listener collections, but |
455 | /// for now this is just for private hijacking. |
456 | std::vector<uint32_t> m_hijacking_masks; |
457 | |
458 | private: |
459 | BroadcasterImpl(const BroadcasterImpl &) = delete; |
460 | const BroadcasterImpl &operator=(const BroadcasterImpl &) = delete; |
461 | }; |
462 | |
463 | typedef std::shared_ptr<BroadcasterImpl> BroadcasterImplSP; |
464 | typedef std::weak_ptr<BroadcasterImpl> BroadcasterImplWP; |
465 | |
466 | BroadcasterImplSP GetBroadcasterImpl() { return m_broadcaster_sp; } |
467 | |
468 | const char *GetHijackingListenerName() { |
469 | return m_broadcaster_sp->GetHijackingListenerName(); |
470 | } |
471 | |
472 | private: |
473 | BroadcasterImplSP m_broadcaster_sp; |
474 | lldb::BroadcasterManagerSP m_manager_sp; |
475 | |
476 | /// The name of this broadcaster object. |
477 | const std::string m_broadcaster_name; |
478 | |
479 | Broadcaster(const Broadcaster &) = delete; |
480 | const Broadcaster &operator=(const Broadcaster &) = delete; |
481 | }; |
482 | |
483 | } // namespace lldb_private |
484 | |
485 | #endif // LLDB_UTILITY_BROADCASTER_H |
486 | |