1 //===-- Broadcaster.h -------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLDB_UTILITY_BROADCASTER_H
11 #define LLDB_UTILITY_BROADCASTER_H
13 #include "lldb/Utility/ConstString.h"
14 #include "lldb/lldb-defines.h"
15 #include "lldb/lldb-forward.h"
17 #include "llvm/ADT/SmallVector.h"
28 namespace lldb_private {
31 namespace lldb_private {
34 namespace lldb_private {
37 namespace lldb_private {
41 namespace lldb_private {
43 //----------------------------------------------------------------------
44 // lldb::BroadcastEventSpec
46 // This class is used to specify a kind of event to register for. The Debugger
47 // maintains a list of BroadcastEventSpec's and when it is made
48 //----------------------------------------------------------------------
49 class BroadcastEventSpec {
51 BroadcastEventSpec(const ConstString &broadcaster_class, uint32_t event_bits)
52 : m_broadcaster_class(broadcaster_class), m_event_bits(event_bits) {}
54 BroadcastEventSpec(const BroadcastEventSpec &rhs);
56 ~BroadcastEventSpec() = default;
58 const ConstString &GetBroadcasterClass() const { return m_broadcaster_class; }
60 uint32_t GetEventBits() const { return m_event_bits; }
62 // Tell whether this BroadcastEventSpec is contained in in_spec. That is: (a)
63 // the two spec's share the same broadcaster class (b) the event bits of this
64 // spec are wholly contained in those of in_spec.
65 bool IsContainedIn(BroadcastEventSpec in_spec) const {
66 if (m_broadcaster_class != in_spec.GetBroadcasterClass())
68 uint32_t in_bits = in_spec.GetEventBits();
69 if (in_bits == m_event_bits)
72 if ((m_event_bits & in_bits) != 0 && (m_event_bits & ~in_bits) == 0)
78 bool operator<(const BroadcastEventSpec &rhs) const;
79 BroadcastEventSpec &operator=(const BroadcastEventSpec &rhs);
82 ConstString m_broadcaster_class;
83 uint32_t m_event_bits;
86 class BroadcasterManager
87 : public std::enable_shared_from_this<BroadcasterManager> {
89 friend class Listener;
95 // Listeners hold onto weak pointers to their broadcaster managers. So they
96 // must be made into shared pointers, which you do with
97 // MakeBroadcasterManager.
99 static lldb::BroadcasterManagerSP MakeBroadcasterManager();
101 ~BroadcasterManager() = default;
103 uint32_t RegisterListenerForEvents(const lldb::ListenerSP &listener_sp,
104 BroadcastEventSpec event_spec);
106 bool UnregisterListenerForEvents(const lldb::ListenerSP &listener_sp,
107 BroadcastEventSpec event_spec);
109 lldb::ListenerSP GetListenerForEventSpec(BroadcastEventSpec event_spec) const;
111 void SignUpListenersForBroadcaster(Broadcaster &broadcaster);
113 void RemoveListener(const lldb::ListenerSP &listener_sp);
115 void RemoveListener(Listener *listener);
120 typedef std::pair<BroadcastEventSpec, lldb::ListenerSP> event_listener_key;
121 typedef std::map<BroadcastEventSpec, lldb::ListenerSP> collection;
122 typedef std::set<lldb::ListenerSP> listener_collection;
123 collection m_event_map;
124 listener_collection m_listeners;
126 mutable std::recursive_mutex m_manager_mutex;
128 // A couple of comparator classes for find_if:
130 class BroadcasterClassMatches {
132 BroadcasterClassMatches(const ConstString &broadcaster_class)
133 : m_broadcaster_class(broadcaster_class) {}
135 ~BroadcasterClassMatches() = default;
137 bool operator()(const event_listener_key input) const {
138 return (input.first.GetBroadcasterClass() == m_broadcaster_class);
142 ConstString m_broadcaster_class;
145 class BroadcastEventSpecMatches {
147 BroadcastEventSpecMatches(BroadcastEventSpec broadcaster_spec)
148 : m_broadcaster_spec(broadcaster_spec) {}
150 ~BroadcastEventSpecMatches() = default;
152 bool operator()(const event_listener_key input) const {
153 return (input.first.IsContainedIn(m_broadcaster_spec));
157 BroadcastEventSpec m_broadcaster_spec;
160 class ListenerMatchesAndSharedBits {
162 explicit ListenerMatchesAndSharedBits(BroadcastEventSpec broadcaster_spec,
163 const lldb::ListenerSP listener_sp)
164 : m_broadcaster_spec(broadcaster_spec), m_listener_sp(listener_sp) {}
166 ~ListenerMatchesAndSharedBits() = default;
168 bool operator()(const event_listener_key input) const {
169 return (input.first.GetBroadcasterClass() ==
170 m_broadcaster_spec.GetBroadcasterClass() &&
171 (input.first.GetEventBits() &
172 m_broadcaster_spec.GetEventBits()) != 0 &&
173 input.second == m_listener_sp);
177 BroadcastEventSpec m_broadcaster_spec;
178 const lldb::ListenerSP m_listener_sp;
181 class ListenerMatches {
183 explicit ListenerMatches(const lldb::ListenerSP in_listener_sp)
184 : m_listener_sp(in_listener_sp) {}
186 ~ListenerMatches() = default;
188 bool operator()(const event_listener_key input) const {
189 if (input.second == m_listener_sp)
196 const lldb::ListenerSP m_listener_sp;
199 class ListenerMatchesPointer {
201 ListenerMatchesPointer(const Listener *in_listener)
202 : m_listener(in_listener) {}
204 ~ListenerMatchesPointer() = default;
206 bool operator()(const event_listener_key input) const {
207 if (input.second.get() == m_listener)
213 bool operator()(const lldb::ListenerSP input) const {
214 if (input.get() == m_listener)
221 const Listener *m_listener;
225 //----------------------------------------------------------------------
226 /// @class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event
227 /// broadcasting class.
229 /// The Broadcaster class is designed to be subclassed by objects that wish to
230 /// vend events in a multi-threaded environment. Broadcaster objects can each
231 /// vend 32 events. Each event is represented by a bit in a 32 bit value and
232 /// these bits can be set:
233 /// @see Broadcaster::SetEventBits(uint32_t)
235 /// @see Broadcaster::ResetEventBits(uint32_t)
236 /// When an event gets set the Broadcaster object will notify the Listener
237 /// object that is listening for the event (if there is one).
239 /// Subclasses should provide broadcast bit definitions for any events they
240 /// vend, typically using an enumeration:
242 /// class Foo : public Broadcaster
245 /// //----------------------------------------------------------
246 /// // Broadcaster event bits definitions.
247 /// //----------------------------------------------------------
250 /// eBroadcastBitOne = (1 << 0),
251 /// eBroadcastBitTwo = (1 << 1),
252 /// eBroadcastBitThree = (1 << 2),
256 //----------------------------------------------------------------------
258 friend class Listener;
262 //------------------------------------------------------------------
263 /// Construct with a broadcaster with a name.
266 /// A NULL terminated C string that contains the name of the
267 /// broadcaster object.
268 //------------------------------------------------------------------
269 Broadcaster(lldb::BroadcasterManagerSP manager_sp, const char *name);
271 //------------------------------------------------------------------
274 /// The destructor is virtual since this class gets subclassed.
275 //------------------------------------------------------------------
276 virtual ~Broadcaster();
278 void CheckInWithManager();
280 //------------------------------------------------------------------
281 /// Broadcast an event which has no associated data.
283 /// @param[in] event_type
284 /// The element from the enum defining this broadcaster's events
285 /// that is being broadcast.
287 /// @param[in] event_data
288 /// User event data that will be owned by the lldb::Event that
289 /// is created internally.
291 /// @param[in] unique
292 /// If true, then only add an event of this type if there isn't
293 /// one already in the queue.
295 //------------------------------------------------------------------
296 void BroadcastEvent(lldb::EventSP &event_sp) {
297 m_broadcaster_sp->BroadcastEvent(event_sp);
300 void BroadcastEventIfUnique(lldb::EventSP &event_sp) {
301 m_broadcaster_sp->BroadcastEventIfUnique(event_sp);
304 void BroadcastEvent(uint32_t event_type,
305 const lldb::EventDataSP &event_data_sp) {
306 m_broadcaster_sp->BroadcastEvent(event_type, event_data_sp);
309 void BroadcastEvent(uint32_t event_type, EventData *event_data = nullptr) {
310 m_broadcaster_sp->BroadcastEvent(event_type, event_data);
313 void BroadcastEventIfUnique(uint32_t event_type,
314 EventData *event_data = nullptr) {
315 m_broadcaster_sp->BroadcastEventIfUnique(event_type, event_data);
318 void Clear() { m_broadcaster_sp->Clear(); }
320 virtual void AddInitialEventsToListener(const lldb::ListenerSP &listener_sp,
321 uint32_t requested_events);
323 //------------------------------------------------------------------
324 /// Listen for any events specified by \a event_mask.
326 /// Only one listener can listen to each event bit in a given Broadcaster.
327 /// Once a listener has acquired an event bit, no other broadcaster will
328 /// have access to it until it is relinquished by the first listener that
329 /// gets it. The actual event bits that get acquired by \a listener may be
330 /// different from what is requested in \a event_mask, and to track this the
331 /// actual event bits that are acquired get returned.
333 /// @param[in] listener
334 /// The Listener object that wants to monitor the events that
335 /// get broadcast by this object.
337 /// @param[in] event_mask
338 /// A bit mask that indicates which events the listener is
339 /// asking to monitor.
342 /// The actual event bits that were acquired by \a listener.
343 //------------------------------------------------------------------
344 uint32_t AddListener(const lldb::ListenerSP &listener_sp,
345 uint32_t event_mask) {
346 return m_broadcaster_sp->AddListener(listener_sp, event_mask);
349 //------------------------------------------------------------------
350 /// Get the NULL terminated C string name of this Broadcaster object.
353 /// The NULL terminated C string name of this Broadcaster.
354 //------------------------------------------------------------------
355 const ConstString &GetBroadcasterName() { return m_broadcaster_name; }
357 //------------------------------------------------------------------
358 /// Get the event name(s) for one or more event bits.
360 /// @param[in] event_mask
361 /// A bit mask that indicates which events to get names for.
364 /// The NULL terminated C string name of this Broadcaster.
365 //------------------------------------------------------------------
366 bool GetEventNames(Stream &s, const uint32_t event_mask,
367 bool prefix_with_broadcaster_name) const {
368 return m_broadcaster_sp->GetEventNames(s, event_mask,
369 prefix_with_broadcaster_name);
372 //------------------------------------------------------------------
373 /// Set the name for an event bit.
375 /// @param[in] event_mask
376 /// A bit mask that indicates which events the listener is
377 /// asking to monitor.
380 /// The NULL terminated C string name of this Broadcaster.
381 //------------------------------------------------------------------
382 void SetEventName(uint32_t event_mask, const char *name) {
383 m_broadcaster_sp->SetEventName(event_mask, name);
386 const char *GetEventName(uint32_t event_mask) const {
387 return m_broadcaster_sp->GetEventName(event_mask);
390 bool EventTypeHasListeners(uint32_t event_type) {
391 return m_broadcaster_sp->EventTypeHasListeners(event_type);
394 //------------------------------------------------------------------
395 /// Removes a Listener from this broadcasters list and frees the event bits
396 /// specified by \a event_mask that were previously acquired by \a listener
397 /// (assuming \a listener was listening to this object) for other listener
400 /// @param[in] listener
401 /// A Listener object that previously called AddListener.
403 /// @param[in] event_mask
404 /// The event bits \a listener wishes to relinquish.
407 /// \b True if the listener was listening to this broadcaster
408 /// and was removed, \b false otherwise.
410 /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
411 //------------------------------------------------------------------
412 bool RemoveListener(const lldb::ListenerSP &listener_sp,
413 uint32_t event_mask = UINT32_MAX) {
414 return m_broadcaster_sp->RemoveListener(listener_sp, event_mask);
417 //------------------------------------------------------------------
418 /// Provides a simple mechanism to temporarily redirect events from
419 /// broadcaster. When you call this function passing in a listener and
420 /// event type mask, all events from the broadcaster matching the mask will
421 /// now go to the hijacking listener. Only one hijack can occur at a time.
422 /// If we need more than this we will have to implement a Listener stack.
424 /// @param[in] listener
425 /// A Listener object. You do not need to call StartListeningForEvents
426 /// for this broadcaster (that would fail anyway since the event bits
427 /// would most likely be taken by the listener(s) you are usurping.
429 /// @param[in] event_mask
430 /// The event bits \a listener wishes to hijack.
433 /// \b True if the event mask could be hijacked, \b false otherwise.
435 /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
436 //------------------------------------------------------------------
437 bool HijackBroadcaster(const lldb::ListenerSP &listener_sp,
438 uint32_t event_mask = UINT32_MAX) {
439 return m_broadcaster_sp->HijackBroadcaster(listener_sp, event_mask);
442 bool IsHijackedForEvent(uint32_t event_mask) {
443 return m_broadcaster_sp->IsHijackedForEvent(event_mask);
446 //------------------------------------------------------------------
447 /// Restore the state of the Broadcaster from a previous hijack attempt.
449 //------------------------------------------------------------------
450 void RestoreBroadcaster() { m_broadcaster_sp->RestoreBroadcaster(); }
452 // This needs to be filled in if you are going to register the broadcaster
453 // with the broadcaster manager and do broadcaster class matching.
454 // FIXME: Probably should make a ManagedBroadcaster subclass with all the bits
456 // with the BroadcasterManager, so that it is clearer how to add one.
457 virtual ConstString &GetBroadcasterClass() const;
459 lldb::BroadcasterManagerSP GetManager();
462 // BroadcasterImpl contains the actual Broadcaster implementation. The
463 // Broadcaster makes a BroadcasterImpl which lives as long as it does. The
464 // Listeners & the Events hold a weak pointer to the BroadcasterImpl, so that
465 // they can survive if a Broadcaster they were listening to is destroyed w/o
466 // their being able to unregister from it (which can happen if the
467 // Broadcasters & Listeners are being destroyed on separate threads
468 // simultaneously. The Broadcaster itself can't be shared out as a weak
469 // pointer, because some things that are broadcasters (e.g. the Target and
470 // the Process) are shared in their own right.
472 // For the most part, the Broadcaster functions dispatch to the
473 // BroadcasterImpl, and are documented in the public Broadcaster API above.
475 class BroadcasterImpl {
476 friend class Listener;
477 friend class Broadcaster;
480 BroadcasterImpl(Broadcaster &broadcaster);
482 ~BroadcasterImpl() = default;
484 void BroadcastEvent(lldb::EventSP &event_sp);
486 void BroadcastEventIfUnique(lldb::EventSP &event_sp);
488 void BroadcastEvent(uint32_t event_type, EventData *event_data = nullptr);
490 void BroadcastEvent(uint32_t event_type,
491 const lldb::EventDataSP &event_data_sp);
493 void BroadcastEventIfUnique(uint32_t event_type,
494 EventData *event_data = nullptr);
498 uint32_t AddListener(const lldb::ListenerSP &listener_sp,
499 uint32_t event_mask);
501 const char *GetBroadcasterName() const {
502 return m_broadcaster.GetBroadcasterName().AsCString();
505 Broadcaster *GetBroadcaster();
507 bool GetEventNames(Stream &s, const uint32_t event_mask,
508 bool prefix_with_broadcaster_name) const;
510 void SetEventName(uint32_t event_mask, const char *name) {
511 m_event_names[event_mask] = name;
514 const char *GetEventName(uint32_t event_mask) const {
515 const auto pos = m_event_names.find(event_mask);
516 if (pos != m_event_names.end())
517 return pos->second.c_str();
521 bool EventTypeHasListeners(uint32_t event_type);
523 bool RemoveListener(lldb_private::Listener *listener,
524 uint32_t event_mask = UINT32_MAX);
526 bool RemoveListener(const lldb::ListenerSP &listener_sp,
527 uint32_t event_mask = UINT32_MAX);
529 bool HijackBroadcaster(const lldb::ListenerSP &listener_sp,
530 uint32_t event_mask = UINT32_MAX);
532 bool IsHijackedForEvent(uint32_t event_mask);
534 void RestoreBroadcaster();
537 void PrivateBroadcastEvent(lldb::EventSP &event_sp, bool unique);
539 const char *GetHijackingListenerName();
541 //------------------------------------------------------------------
543 //------------------------------------------------------------------
544 typedef llvm::SmallVector<std::pair<lldb::ListenerWP, uint32_t>, 4>
546 typedef std::map<uint32_t, std::string> event_names_map;
548 llvm::SmallVector<std::pair<lldb::ListenerSP, uint32_t &>, 4>
551 Broadcaster &m_broadcaster; ///< The broadcaster that this implements
552 event_names_map m_event_names; ///< Optionally define event names for
553 ///readability and logging for each event bit
554 collection m_listeners; ///< A list of Listener / event_mask pairs that are
555 ///listening to this broadcaster.
557 m_listeners_mutex; ///< A mutex that protects \a m_listeners.
558 std::vector<lldb::ListenerSP> m_hijacking_listeners; // A simple mechanism
559 // to intercept events
560 // from a broadcaster
561 std::vector<uint32_t> m_hijacking_masks; // At some point we may want to
562 // have a stack or Listener
563 // collections, but for now this is just for private hijacking.
566 //------------------------------------------------------------------
567 // For Broadcaster only
568 //------------------------------------------------------------------
569 DISALLOW_COPY_AND_ASSIGN(BroadcasterImpl);
572 typedef std::shared_ptr<BroadcasterImpl> BroadcasterImplSP;
573 typedef std::weak_ptr<BroadcasterImpl> BroadcasterImplWP;
575 BroadcasterImplSP GetBroadcasterImpl() { return m_broadcaster_sp; }
577 const char *GetHijackingListenerName() {
578 return m_broadcaster_sp->GetHijackingListenerName();
580 //------------------------------------------------------------------
581 // Classes that inherit from Broadcaster can see and modify these
582 //------------------------------------------------------------------
585 //------------------------------------------------------------------
586 // For Broadcaster only
587 //------------------------------------------------------------------
588 BroadcasterImplSP m_broadcaster_sp;
589 lldb::BroadcasterManagerSP m_manager_sp;
591 m_broadcaster_name; ///< The name of this broadcaster object.
593 DISALLOW_COPY_AND_ASSIGN(Broadcaster);
596 } // namespace lldb_private
598 #endif // LLDB_UTILITY_BROADCASTER_H