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 liblldb_Broadcaster_h_
11 #define liblldb_Broadcaster_h_
22 // Other libraries and framework includes
24 #include "lldb/Core/ConstString.h"
25 #include "lldb/lldb-private.h"
27 #include "llvm/ADT/SmallVector.h"
29 namespace lldb_private {
31 //----------------------------------------------------------------------
32 // lldb::BroadcastEventSpec
34 // This class is used to specify a kind of event to register for. The Debugger
35 // maintains a list of BroadcastEventSpec's and when it is made
36 //----------------------------------------------------------------------
37 class BroadcastEventSpec {
39 BroadcastEventSpec(const ConstString &broadcaster_class, uint32_t event_bits)
40 : m_broadcaster_class(broadcaster_class), m_event_bits(event_bits) {}
42 BroadcastEventSpec(const BroadcastEventSpec &rhs);
44 ~BroadcastEventSpec() = default;
46 const ConstString &GetBroadcasterClass() const { return m_broadcaster_class; }
48 uint32_t GetEventBits() const { return m_event_bits; }
50 // Tell whether this BroadcastEventSpec is contained in in_spec.
52 // (a) the two spec's share the same broadcaster class
53 // (b) the event bits of this spec are wholly contained in those of in_spec.
54 bool IsContainedIn(BroadcastEventSpec in_spec) const {
55 if (m_broadcaster_class != in_spec.GetBroadcasterClass())
57 uint32_t in_bits = in_spec.GetEventBits();
58 if (in_bits == m_event_bits)
61 if ((m_event_bits & in_bits) != 0 && (m_event_bits & ~in_bits) == 0)
67 bool operator<(const BroadcastEventSpec &rhs) const;
68 BroadcastEventSpec &operator=(const BroadcastEventSpec &rhs);
71 ConstString m_broadcaster_class;
72 uint32_t m_event_bits;
75 class BroadcasterManager
76 : public std::enable_shared_from_this<BroadcasterManager> {
78 friend class Listener;
84 // Listeners hold onto weak pointers to their broadcaster managers. So they
86 // made into shared pointers, which you do with MakeBroadcasterManager.
88 static lldb::BroadcasterManagerSP MakeBroadcasterManager();
90 ~BroadcasterManager() = default;
92 uint32_t RegisterListenerForEvents(const lldb::ListenerSP &listener_sp,
93 BroadcastEventSpec event_spec);
95 bool UnregisterListenerForEvents(const lldb::ListenerSP &listener_sp,
96 BroadcastEventSpec event_spec);
98 lldb::ListenerSP GetListenerForEventSpec(BroadcastEventSpec event_spec) const;
100 void SignUpListenersForBroadcaster(Broadcaster &broadcaster);
102 void RemoveListener(const lldb::ListenerSP &listener_sp);
104 void RemoveListener(Listener *listener);
109 typedef std::pair<BroadcastEventSpec, lldb::ListenerSP> event_listener_key;
110 typedef std::map<BroadcastEventSpec, lldb::ListenerSP> collection;
111 typedef std::set<lldb::ListenerSP> listener_collection;
112 collection m_event_map;
113 listener_collection m_listeners;
115 mutable std::recursive_mutex m_manager_mutex;
117 // A couple of comparator classes for find_if:
119 class BroadcasterClassMatches {
121 BroadcasterClassMatches(const ConstString &broadcaster_class)
122 : m_broadcaster_class(broadcaster_class) {}
124 ~BroadcasterClassMatches() = default;
126 bool operator()(const event_listener_key input) const {
127 return (input.first.GetBroadcasterClass() == m_broadcaster_class);
131 ConstString m_broadcaster_class;
134 class BroadcastEventSpecMatches {
136 BroadcastEventSpecMatches(BroadcastEventSpec broadcaster_spec)
137 : m_broadcaster_spec(broadcaster_spec) {}
139 ~BroadcastEventSpecMatches() = default;
141 bool operator()(const event_listener_key input) const {
142 return (input.first.IsContainedIn(m_broadcaster_spec));
146 BroadcastEventSpec m_broadcaster_spec;
149 class ListenerMatchesAndSharedBits {
151 explicit ListenerMatchesAndSharedBits(BroadcastEventSpec broadcaster_spec,
152 const lldb::ListenerSP listener_sp)
153 : m_broadcaster_spec(broadcaster_spec), m_listener_sp(listener_sp) {}
155 ~ListenerMatchesAndSharedBits() = default;
157 bool operator()(const event_listener_key input) const {
158 return (input.first.GetBroadcasterClass() ==
159 m_broadcaster_spec.GetBroadcasterClass() &&
160 (input.first.GetEventBits() &
161 m_broadcaster_spec.GetEventBits()) != 0 &&
162 input.second == m_listener_sp);
166 BroadcastEventSpec m_broadcaster_spec;
167 const lldb::ListenerSP m_listener_sp;
170 class ListenerMatches {
172 explicit ListenerMatches(const lldb::ListenerSP in_listener_sp)
173 : m_listener_sp(in_listener_sp) {}
175 ~ListenerMatches() = default;
177 bool operator()(const event_listener_key input) const {
178 if (input.second == m_listener_sp)
185 const lldb::ListenerSP m_listener_sp;
188 class ListenerMatchesPointer {
190 ListenerMatchesPointer(const Listener *in_listener)
191 : m_listener(in_listener) {}
193 ~ListenerMatchesPointer() = default;
195 bool operator()(const event_listener_key input) const {
196 if (input.second.get() == m_listener)
202 bool operator()(const lldb::ListenerSP input) const {
203 if (input.get() == m_listener)
210 const Listener *m_listener;
214 //----------------------------------------------------------------------
215 /// @class Broadcaster Broadcaster.h "lldb/Core/Broadcaster.h"
216 /// @brief An event broadcasting class.
218 /// The Broadcaster class is designed to be subclassed by objects that
219 /// wish to vend events in a multi-threaded environment. Broadcaster
220 /// objects can each vend 32 events. Each event is represented by a bit
221 /// in a 32 bit value and these bits can be set:
222 /// @see Broadcaster::SetEventBits(uint32_t)
224 /// @see Broadcaster::ResetEventBits(uint32_t)
225 /// When an event gets set the Broadcaster object will notify the
226 /// Listener object that is listening for the event (if there is one).
228 /// Subclasses should provide broadcast bit definitions for any events
229 /// they vend, typically using an enumeration:
231 /// class Foo : public Broadcaster
234 /// //----------------------------------------------------------
235 /// // Broadcaster event bits definitions.
236 /// //----------------------------------------------------------
239 /// eBroadcastBitOne = (1 << 0),
240 /// eBroadcastBitTwo = (1 << 1),
241 /// eBroadcastBitThree = (1 << 2),
245 //----------------------------------------------------------------------
247 friend class Listener;
251 //------------------------------------------------------------------
252 /// Construct with a broadcaster with a name.
255 /// A NULL terminated C string that contains the name of the
256 /// broadcaster object.
257 //------------------------------------------------------------------
258 Broadcaster(lldb::BroadcasterManagerSP manager_sp, const char *name);
260 //------------------------------------------------------------------
263 /// The destructor is virtual since this class gets subclassed.
264 //------------------------------------------------------------------
265 virtual ~Broadcaster();
267 void CheckInWithManager();
269 //------------------------------------------------------------------
270 /// Broadcast an event which has no associated data.
272 /// @param[in] event_type
273 /// The element from the enum defining this broadcaster's events
274 /// that is being broadcast.
276 /// @param[in] event_data
277 /// User event data that will be owned by the lldb::Event that
278 /// is created internally.
280 /// @param[in] unique
281 /// If true, then only add an event of this type if there isn't
282 /// one already in the queue.
284 //------------------------------------------------------------------
285 void BroadcastEvent(lldb::EventSP &event_sp) {
286 m_broadcaster_sp->BroadcastEvent(event_sp);
289 void BroadcastEventIfUnique(lldb::EventSP &event_sp) {
290 m_broadcaster_sp->BroadcastEventIfUnique(event_sp);
293 void BroadcastEvent(uint32_t event_type,
294 const lldb::EventDataSP &event_data_sp) {
295 m_broadcaster_sp->BroadcastEvent(event_type, event_data_sp);
298 void BroadcastEvent(uint32_t event_type, EventData *event_data = nullptr) {
299 m_broadcaster_sp->BroadcastEvent(event_type, event_data);
302 void BroadcastEventIfUnique(uint32_t event_type,
303 EventData *event_data = nullptr) {
304 m_broadcaster_sp->BroadcastEventIfUnique(event_type, event_data);
307 void Clear() { m_broadcaster_sp->Clear(); }
309 virtual void AddInitialEventsToListener(const lldb::ListenerSP &listener_sp,
310 uint32_t requested_events);
312 //------------------------------------------------------------------
313 /// Listen for any events specified by \a event_mask.
315 /// Only one listener can listen to each event bit in a given
316 /// Broadcaster. Once a listener has acquired an event bit, no
317 /// other broadcaster will have access to it until it is
318 /// relinquished by the first listener that gets it. The actual
319 /// event bits that get acquired by \a listener may be different
320 /// from what is requested in \a event_mask, and to track this the
321 /// actual event bits that are acquired get returned.
323 /// @param[in] listener
324 /// The Listener object that wants to monitor the events that
325 /// get broadcast by this object.
327 /// @param[in] event_mask
328 /// A bit mask that indicates which events the listener is
329 /// asking to monitor.
332 /// The actual event bits that were acquired by \a listener.
333 //------------------------------------------------------------------
334 uint32_t AddListener(const lldb::ListenerSP &listener_sp,
335 uint32_t event_mask) {
336 return m_broadcaster_sp->AddListener(listener_sp, event_mask);
339 //------------------------------------------------------------------
340 /// Get the NULL terminated C string name of this Broadcaster
344 /// The NULL terminated C string name of this Broadcaster.
345 //------------------------------------------------------------------
346 const ConstString &GetBroadcasterName() { return m_broadcaster_name; }
348 //------------------------------------------------------------------
349 /// Get the event name(s) for one or more event bits.
351 /// @param[in] event_mask
352 /// A bit mask that indicates which events to get names for.
355 /// The NULL terminated C string name of this Broadcaster.
356 //------------------------------------------------------------------
357 bool GetEventNames(Stream &s, const uint32_t event_mask,
358 bool prefix_with_broadcaster_name) const {
359 return m_broadcaster_sp->GetEventNames(s, event_mask,
360 prefix_with_broadcaster_name);
363 //------------------------------------------------------------------
364 /// Set the name for an event bit.
366 /// @param[in] event_mask
367 /// A bit mask that indicates which events the listener is
368 /// asking to monitor.
371 /// The NULL terminated C string name of this Broadcaster.
372 //------------------------------------------------------------------
373 void SetEventName(uint32_t event_mask, const char *name) {
374 m_broadcaster_sp->SetEventName(event_mask, name);
377 const char *GetEventName(uint32_t event_mask) const {
378 return m_broadcaster_sp->GetEventName(event_mask);
381 bool EventTypeHasListeners(uint32_t event_type) {
382 return m_broadcaster_sp->EventTypeHasListeners(event_type);
385 //------------------------------------------------------------------
386 /// Removes a Listener from this broadcasters list and frees the
387 /// event bits specified by \a event_mask that were previously
388 /// acquired by \a listener (assuming \a listener was listening to
389 /// this object) for other listener objects to use.
391 /// @param[in] listener
392 /// A Listener object that previously called AddListener.
394 /// @param[in] event_mask
395 /// The event bits \a listener wishes to relinquish.
398 /// \b True if the listener was listening to this broadcaster
399 /// and was removed, \b false otherwise.
401 /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
402 //------------------------------------------------------------------
403 bool RemoveListener(const lldb::ListenerSP &listener_sp,
404 uint32_t event_mask = UINT32_MAX) {
405 return m_broadcaster_sp->RemoveListener(listener_sp, event_mask);
408 //------------------------------------------------------------------
409 /// Provides a simple mechanism to temporarily redirect events from
410 /// broadcaster. When you call this function passing in a listener and
411 /// event type mask, all events from the broadcaster matching the mask
412 /// will now go to the hijacking listener.
413 /// Only one hijack can occur at a time. If we need more than this we
414 /// will have to implement a Listener stack.
416 /// @param[in] listener
417 /// A Listener object. You do not need to call StartListeningForEvents
418 /// for this broadcaster (that would fail anyway since the event bits
419 /// would most likely be taken by the listener(s) you are usurping.
421 /// @param[in] event_mask
422 /// The event bits \a listener wishes to hijack.
425 /// \b True if the event mask could be hijacked, \b false otherwise.
427 /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t)
428 //------------------------------------------------------------------
429 bool HijackBroadcaster(const lldb::ListenerSP &listener_sp,
430 uint32_t event_mask = UINT32_MAX) {
431 return m_broadcaster_sp->HijackBroadcaster(listener_sp, event_mask);
434 bool IsHijackedForEvent(uint32_t event_mask) {
435 return m_broadcaster_sp->IsHijackedForEvent(event_mask);
438 //------------------------------------------------------------------
439 /// Restore the state of the Broadcaster from a previous hijack attempt.
441 //------------------------------------------------------------------
442 void RestoreBroadcaster() { m_broadcaster_sp->RestoreBroadcaster(); }
444 // This needs to be filled in if you are going to register the broadcaster
445 // with the broadcaster
446 // manager and do broadcaster class matching.
447 // FIXME: Probably should make a ManagedBroadcaster subclass with all the bits
449 // with the BroadcasterManager, so that it is clearer how to add one.
450 virtual ConstString &GetBroadcasterClass() const;
452 lldb::BroadcasterManagerSP GetManager();
455 // BroadcasterImpl contains the actual Broadcaster implementation. The
456 // Broadcaster makes a BroadcasterImpl
457 // which lives as long as it does. The Listeners & the Events hold a weak
458 // pointer to the BroadcasterImpl,
459 // so that they can survive if a Broadcaster they were listening to is
460 // destroyed w/o their being able to
461 // unregister from it (which can happen if the Broadcasters & Listeners are
462 // being destroyed on separate threads
464 // The Broadcaster itself can't be shared out as a weak pointer, because some
465 // things that are broadcasters
466 // (e.g. the Target and the Process) are shared in their own right.
468 // For the most part, the Broadcaster functions dispatch to the
469 // BroadcasterImpl, and are documented in the
470 // public Broadcaster API above.
472 class BroadcasterImpl {
473 friend class Listener;
474 friend class Broadcaster;
477 BroadcasterImpl(Broadcaster &broadcaster);
479 ~BroadcasterImpl() = default;
481 void BroadcastEvent(lldb::EventSP &event_sp);
483 void BroadcastEventIfUnique(lldb::EventSP &event_sp);
485 void BroadcastEvent(uint32_t event_type, EventData *event_data = nullptr);
487 void BroadcastEvent(uint32_t event_type,
488 const lldb::EventDataSP &event_data_sp);
490 void BroadcastEventIfUnique(uint32_t event_type,
491 EventData *event_data = nullptr);
495 uint32_t AddListener(const lldb::ListenerSP &listener_sp,
496 uint32_t event_mask);
498 const char *GetBroadcasterName() const {
499 return m_broadcaster.GetBroadcasterName().AsCString();
502 Broadcaster *GetBroadcaster();
504 bool GetEventNames(Stream &s, const uint32_t event_mask,
505 bool prefix_with_broadcaster_name) const;
507 void SetEventName(uint32_t event_mask, const char *name) {
508 m_event_names[event_mask] = name;
511 const char *GetEventName(uint32_t event_mask) const {
512 const auto pos = m_event_names.find(event_mask);
513 if (pos != m_event_names.end())
514 return pos->second.c_str();
518 bool EventTypeHasListeners(uint32_t event_type);
520 bool RemoveListener(lldb_private::Listener *listener,
521 uint32_t event_mask = UINT32_MAX);
523 bool RemoveListener(const lldb::ListenerSP &listener_sp,
524 uint32_t event_mask = UINT32_MAX);
526 bool HijackBroadcaster(const lldb::ListenerSP &listener_sp,
527 uint32_t event_mask = UINT32_MAX);
529 bool IsHijackedForEvent(uint32_t event_mask);
531 void RestoreBroadcaster();
534 void PrivateBroadcastEvent(lldb::EventSP &event_sp, bool unique);
536 const char *GetHijackingListenerName();
538 //------------------------------------------------------------------
540 //------------------------------------------------------------------
541 typedef llvm::SmallVector<std::pair<lldb::ListenerWP, uint32_t>, 4>
543 typedef std::map<uint32_t, std::string> event_names_map;
545 llvm::SmallVector<std::pair<lldb::ListenerSP, uint32_t &>, 4>
548 Broadcaster &m_broadcaster; ///< The broadcsater that this implements
549 event_names_map m_event_names; ///< Optionally define event names for
550 ///readability and logging for each event bit
551 collection m_listeners; ///< A list of Listener / event_mask pairs that are
552 ///listening to this broadcaster.
554 m_listeners_mutex; ///< A mutex that protects \a m_listeners.
555 std::vector<lldb::ListenerSP> m_hijacking_listeners; // A simple mechanism
556 // to intercept events
557 // from a broadcaster
558 std::vector<uint32_t> m_hijacking_masks; // At some point we may want to
559 // have a stack or Listener
560 // collections, but for now this is just for private hijacking.
563 //------------------------------------------------------------------
564 // For Broadcaster only
565 //------------------------------------------------------------------
566 DISALLOW_COPY_AND_ASSIGN(BroadcasterImpl);
569 typedef std::shared_ptr<BroadcasterImpl> BroadcasterImplSP;
570 typedef std::weak_ptr<BroadcasterImpl> BroadcasterImplWP;
572 BroadcasterImplSP GetBroadcasterImpl() { return m_broadcaster_sp; }
574 const char *GetHijackingListenerName() {
575 return m_broadcaster_sp->GetHijackingListenerName();
577 //------------------------------------------------------------------
578 // Classes that inherit from Broadcaster can see and modify these
579 //------------------------------------------------------------------
582 //------------------------------------------------------------------
583 // For Broadcaster only
584 //------------------------------------------------------------------
585 BroadcasterImplSP m_broadcaster_sp;
586 lldb::BroadcasterManagerSP m_manager_sp;
588 m_broadcaster_name; ///< The name of this broadcaster object.
590 DISALLOW_COPY_AND_ASSIGN(Broadcaster);
593 } // namespace lldb_private
595 #endif // liblldb_Broadcaster_h_