diff options
Diffstat (limited to 'include/lldb/Utility/Broadcaster.h')
| -rw-r--r-- | include/lldb/Utility/Broadcaster.h | 254 |
1 files changed, 107 insertions, 147 deletions
diff --git a/include/lldb/Utility/Broadcaster.h b/include/lldb/Utility/Broadcaster.h index 8763a63b0d5e..fe4d1ca479b8 100644 --- a/include/lldb/Utility/Broadcaster.h +++ b/include/lldb/Utility/Broadcaster.h @@ -1,9 +1,8 @@ //===-- Broadcaster.h -------------------------------------------*- C++ -*-===// // -// The LLVM Compiler Infrastructure -// -// This file is distributed under the University of Illinois Open Source -// License. See LICENSE.TXT for details. +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// @@ -27,51 +26,41 @@ namespace lldb_private { class Broadcaster; -} -namespace lldb_private { class EventData; -} -namespace lldb_private { class Listener; -} -namespace lldb_private { class Stream; -} +} // namespace lldb_private namespace lldb_private { -//---------------------------------------------------------------------- -// lldb::BroadcastEventSpec -// -// This class is used to specify a kind of event to register for. The Debugger -// maintains a list of BroadcastEventSpec's and when it is made -//---------------------------------------------------------------------- +/// lldb::BroadcastEventSpec +/// +/// This class is used to specify a kind of event to register for. The +/// Debugger maintains a list of BroadcastEventSpec's and when it is made class BroadcastEventSpec { public: - BroadcastEventSpec(const ConstString &broadcaster_class, uint32_t event_bits) + BroadcastEventSpec(ConstString broadcaster_class, uint32_t event_bits) : m_broadcaster_class(broadcaster_class), m_event_bits(event_bits) {} - BroadcastEventSpec(const BroadcastEventSpec &rhs); - ~BroadcastEventSpec() = default; - const ConstString &GetBroadcasterClass() const { return m_broadcaster_class; } + ConstString GetBroadcasterClass() const { return m_broadcaster_class; } uint32_t GetEventBits() const { return m_event_bits; } - // Tell whether this BroadcastEventSpec is contained in in_spec. That is: (a) - // the two spec's share the same broadcaster class (b) the event bits of this - // spec are wholly contained in those of in_spec. - bool IsContainedIn(BroadcastEventSpec in_spec) const { + /// Tell whether this BroadcastEventSpec is contained in in_spec. That is: + /// (a) the two spec's share the same broadcaster class (b) the event bits of + /// this spec are wholly contained in those of in_spec. + bool IsContainedIn(const BroadcastEventSpec &in_spec) const { if (m_broadcaster_class != in_spec.GetBroadcasterClass()) return false; uint32_t in_bits = in_spec.GetEventBits(); if (in_bits == m_event_bits) return true; - else { - if ((m_event_bits & in_bits) != 0 && (m_event_bits & ~in_bits) == 0) - return true; - } + + if ((m_event_bits & in_bits) != 0 && (m_event_bits & ~in_bits) == 0) + return true; + return false; } @@ -92,21 +81,21 @@ protected: BroadcasterManager(); public: - // Listeners hold onto weak pointers to their broadcaster managers. So they - // must be made into shared pointers, which you do with - // MakeBroadcasterManager. - + /// Listeners hold onto weak pointers to their broadcaster managers. So they + /// must be made into shared pointers, which you do with + /// MakeBroadcasterManager. static lldb::BroadcasterManagerSP MakeBroadcasterManager(); ~BroadcasterManager() = default; uint32_t RegisterListenerForEvents(const lldb::ListenerSP &listener_sp, - BroadcastEventSpec event_spec); + const BroadcastEventSpec &event_spec); bool UnregisterListenerForEvents(const lldb::ListenerSP &listener_sp, - BroadcastEventSpec event_spec); + const BroadcastEventSpec &event_spec); - lldb::ListenerSP GetListenerForEventSpec(BroadcastEventSpec event_spec) const; + lldb::ListenerSP + GetListenerForEventSpec(const BroadcastEventSpec &event_spec) const; void SignUpListenersForBroadcaster(Broadcaster &broadcaster); @@ -129,12 +118,12 @@ private: class BroadcasterClassMatches { public: - BroadcasterClassMatches(const ConstString &broadcaster_class) + BroadcasterClassMatches(ConstString broadcaster_class) : m_broadcaster_class(broadcaster_class) {} ~BroadcasterClassMatches() = default; - bool operator()(const event_listener_key input) const { + bool operator()(const event_listener_key &input) const { return (input.first.GetBroadcasterClass() == m_broadcaster_class); } @@ -144,12 +133,12 @@ private: class BroadcastEventSpecMatches { public: - BroadcastEventSpecMatches(BroadcastEventSpec broadcaster_spec) + BroadcastEventSpecMatches(const BroadcastEventSpec &broadcaster_spec) : m_broadcaster_spec(broadcaster_spec) {} ~BroadcastEventSpecMatches() = default; - bool operator()(const event_listener_key input) const { + bool operator()(const event_listener_key &input) const { return (input.first.IsContainedIn(m_broadcaster_spec)); } @@ -159,13 +148,14 @@ private: class ListenerMatchesAndSharedBits { public: - explicit ListenerMatchesAndSharedBits(BroadcastEventSpec broadcaster_spec, - const lldb::ListenerSP listener_sp) + explicit ListenerMatchesAndSharedBits( + const BroadcastEventSpec &broadcaster_spec, + const lldb::ListenerSP &listener_sp) : m_broadcaster_spec(broadcaster_spec), m_listener_sp(listener_sp) {} ~ListenerMatchesAndSharedBits() = default; - bool operator()(const event_listener_key input) const { + bool operator()(const event_listener_key &input) const { return (input.first.GetBroadcasterClass() == m_broadcaster_spec.GetBroadcasterClass() && (input.first.GetEventBits() & @@ -180,16 +170,16 @@ private: class ListenerMatches { public: - explicit ListenerMatches(const lldb::ListenerSP in_listener_sp) + explicit ListenerMatches(const lldb::ListenerSP &in_listener_sp) : m_listener_sp(in_listener_sp) {} ~ListenerMatches() = default; - bool operator()(const event_listener_key input) const { + bool operator()(const event_listener_key &input) const { if (input.second == m_listener_sp) return true; - else - return false; + + return false; } private: @@ -203,18 +193,18 @@ private: ~ListenerMatchesPointer() = default; - bool operator()(const event_listener_key input) const { + bool operator()(const event_listener_key &input) const { if (input.second.get() == m_listener) return true; - else - return false; + + return false; } - bool operator()(const lldb::ListenerSP input) const { + bool operator()(const lldb::ListenerSP &input) const { if (input.get() == m_listener) return true; - else - return false; + + return false; } private: @@ -222,17 +212,16 @@ private: }; }; -//---------------------------------------------------------------------- -/// @class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event +/// \class Broadcaster Broadcaster.h "lldb/Utility/Broadcaster.h" An event /// broadcasting class. /// /// The Broadcaster class is designed to be subclassed by objects that wish to /// vend events in a multi-threaded environment. Broadcaster objects can each /// vend 32 events. Each event is represented by a bit in a 32 bit value and /// these bits can be set: -/// @see Broadcaster::SetEventBits(uint32_t) +/// \see Broadcaster::SetEventBits(uint32_t) /// or cleared: -/// @see Broadcaster::ResetEventBits(uint32_t) +/// \see Broadcaster::ResetEventBits(uint32_t) /// When an event gets set the Broadcaster object will notify the Listener /// object that is listening for the event (if there is one). /// @@ -242,9 +231,7 @@ private: /// class Foo : public Broadcaster /// { /// public: -/// //---------------------------------------------------------- /// // Broadcaster event bits definitions. -/// //---------------------------------------------------------- /// enum /// { /// eBroadcastBitOne = (1 << 0), @@ -253,46 +240,39 @@ private: /// ... /// }; /// \endcode -//---------------------------------------------------------------------- class Broadcaster { friend class Listener; friend class Event; public: - //------------------------------------------------------------------ /// Construct with a broadcaster with a name. /// - /// @param[in] name + /// \param[in] name /// A NULL terminated C string that contains the name of the /// broadcaster object. - //------------------------------------------------------------------ Broadcaster(lldb::BroadcasterManagerSP manager_sp, const char *name); - //------------------------------------------------------------------ /// Destructor. /// /// The destructor is virtual since this class gets subclassed. - //------------------------------------------------------------------ virtual ~Broadcaster(); void CheckInWithManager(); - //------------------------------------------------------------------ /// Broadcast an event which has no associated data. /// - /// @param[in] event_type + /// \param[in] event_type /// The element from the enum defining this broadcaster's events /// that is being broadcast. /// - /// @param[in] event_data + /// \param[in] event_data /// User event data that will be owned by the lldb::Event that /// is created internally. /// - /// @param[in] unique + /// \param[in] unique /// If true, then only add an event of this type if there isn't /// one already in the queue. /// - //------------------------------------------------------------------ void BroadcastEvent(lldb::EventSP &event_sp) { m_broadcaster_sp->BroadcastEvent(event_sp); } @@ -320,7 +300,6 @@ public: virtual void AddInitialEventsToListener(const lldb::ListenerSP &listener_sp, uint32_t requested_events); - //------------------------------------------------------------------ /// Listen for any events specified by \a event_mask. /// /// Only one listener can listen to each event bit in a given Broadcaster. @@ -330,55 +309,48 @@ public: /// different from what is requested in \a event_mask, and to track this the /// actual event bits that are acquired get returned. /// - /// @param[in] listener + /// \param[in] listener /// The Listener object that wants to monitor the events that /// get broadcast by this object. /// - /// @param[in] event_mask + /// \param[in] event_mask /// A bit mask that indicates which events the listener is /// asking to monitor. /// - /// @return + /// \return /// The actual event bits that were acquired by \a listener. - //------------------------------------------------------------------ uint32_t AddListener(const lldb::ListenerSP &listener_sp, uint32_t event_mask) { return m_broadcaster_sp->AddListener(listener_sp, event_mask); } - //------------------------------------------------------------------ /// Get the NULL terminated C string name of this Broadcaster object. /// - /// @return + /// \return /// The NULL terminated C string name of this Broadcaster. - //------------------------------------------------------------------ - const ConstString &GetBroadcasterName() { return m_broadcaster_name; } + ConstString GetBroadcasterName() { return m_broadcaster_name; } - //------------------------------------------------------------------ /// Get the event name(s) for one or more event bits. /// - /// @param[in] event_mask + /// \param[in] event_mask /// A bit mask that indicates which events to get names for. /// - /// @return + /// \return /// The NULL terminated C string name of this Broadcaster. - //------------------------------------------------------------------ bool GetEventNames(Stream &s, const uint32_t event_mask, bool prefix_with_broadcaster_name) const { return m_broadcaster_sp->GetEventNames(s, event_mask, prefix_with_broadcaster_name); } - //------------------------------------------------------------------ /// Set the name for an event bit. /// - /// @param[in] event_mask + /// \param[in] event_mask /// A bit mask that indicates which events the listener is /// asking to monitor. /// - /// @return + /// \return /// The NULL terminated C string name of this Broadcaster. - //------------------------------------------------------------------ void SetEventName(uint32_t event_mask, const char *name) { m_broadcaster_sp->SetEventName(event_mask, name); } @@ -391,49 +363,45 @@ public: return m_broadcaster_sp->EventTypeHasListeners(event_type); } - //------------------------------------------------------------------ /// Removes a Listener from this broadcasters list and frees the event bits /// specified by \a event_mask that were previously acquired by \a listener /// (assuming \a listener was listening to this object) for other listener /// objects to use. /// - /// @param[in] listener + /// \param[in] listener /// A Listener object that previously called AddListener. /// - /// @param[in] event_mask + /// \param[in] event_mask /// The event bits \a listener wishes to relinquish. /// - /// @return + /// \return /// \b True if the listener was listening to this broadcaster /// and was removed, \b false otherwise. /// - /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t) - //------------------------------------------------------------------ + /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t) bool RemoveListener(const lldb::ListenerSP &listener_sp, uint32_t event_mask = UINT32_MAX) { return m_broadcaster_sp->RemoveListener(listener_sp, event_mask); } - //------------------------------------------------------------------ /// Provides a simple mechanism to temporarily redirect events from /// broadcaster. When you call this function passing in a listener and /// event type mask, all events from the broadcaster matching the mask will /// now go to the hijacking listener. Only one hijack can occur at a time. /// If we need more than this we will have to implement a Listener stack. /// - /// @param[in] listener + /// \param[in] listener /// A Listener object. You do not need to call StartListeningForEvents /// for this broadcaster (that would fail anyway since the event bits /// would most likely be taken by the listener(s) you are usurping. /// - /// @param[in] event_mask + /// \param[in] event_mask /// The event bits \a listener wishes to hijack. /// - /// @return + /// \return /// \b True if the event mask could be hijacked, \b false otherwise. /// - /// @see uint32_t Broadcaster::AddListener (Listener*, uint32_t) - //------------------------------------------------------------------ + /// \see uint32_t Broadcaster::AddListener (Listener*, uint32_t) bool HijackBroadcaster(const lldb::ListenerSP &listener_sp, uint32_t event_mask = UINT32_MAX) { return m_broadcaster_sp->HijackBroadcaster(listener_sp, event_mask); @@ -443,35 +411,31 @@ public: return m_broadcaster_sp->IsHijackedForEvent(event_mask); } - //------------------------------------------------------------------ /// Restore the state of the Broadcaster from a previous hijack attempt. - /// - //------------------------------------------------------------------ void RestoreBroadcaster() { m_broadcaster_sp->RestoreBroadcaster(); } - // This needs to be filled in if you are going to register the broadcaster - // with the broadcaster manager and do broadcaster class matching. - // FIXME: Probably should make a ManagedBroadcaster subclass with all the bits - // needed to work - // with the BroadcasterManager, so that it is clearer how to add one. + /// This needs to be filled in if you are going to register the broadcaster + /// with the broadcaster manager and do broadcaster class matching. + /// FIXME: Probably should make a ManagedBroadcaster subclass with all the + /// bits needed to work with the BroadcasterManager, so that it is clearer + /// how to add one. virtual ConstString &GetBroadcasterClass() const; lldb::BroadcasterManagerSP GetManager(); protected: - // BroadcasterImpl contains the actual Broadcaster implementation. The - // Broadcaster makes a BroadcasterImpl which lives as long as it does. The - // Listeners & the Events hold a weak pointer to the BroadcasterImpl, so that - // they can survive if a Broadcaster they were listening to is destroyed w/o - // their being able to unregister from it (which can happen if the - // Broadcasters & Listeners are being destroyed on separate threads - // simultaneously. The Broadcaster itself can't be shared out as a weak - // pointer, because some things that are broadcasters (e.g. the Target and - // the Process) are shared in their own right. - // - // For the most part, the Broadcaster functions dispatch to the - // BroadcasterImpl, and are documented in the public Broadcaster API above. - + /// BroadcasterImpl contains the actual Broadcaster implementation. The + /// Broadcaster makes a BroadcasterImpl which lives as long as it does. The + /// Listeners & the Events hold a weak pointer to the BroadcasterImpl, so + /// that they can survive if a Broadcaster they were listening to is + /// destroyed w/o their being able to unregister from it (which can happen if + /// the Broadcasters & Listeners are being destroyed on separate threads + /// simultaneously. The Broadcaster itself can't be shared out as a weak + /// pointer, because some things that are broadcasters (e.g. the Target and + /// the Process) are shared in their own right. + /// + /// For the most part, the Broadcaster functions dispatch to the + /// BroadcasterImpl, and are documented in the public Broadcaster API above. class BroadcasterImpl { friend class Listener; friend class Broadcaster; @@ -538,9 +502,6 @@ protected: const char *GetHijackingListenerName(); - //------------------------------------------------------------------ - // - //------------------------------------------------------------------ typedef llvm::SmallVector<std::pair<lldb::ListenerWP, uint32_t>, 4> collection; typedef std::map<uint32_t, std::string> event_names_map; @@ -548,24 +509,28 @@ protected: llvm::SmallVector<std::pair<lldb::ListenerSP, uint32_t &>, 4> GetListeners(); - Broadcaster &m_broadcaster; ///< The broadcaster that this implements - event_names_map m_event_names; ///< Optionally define event names for - ///readability and logging for each event bit - collection m_listeners; ///< A list of Listener / event_mask pairs that are - ///listening to this broadcaster. - std::recursive_mutex - m_listeners_mutex; ///< A mutex that protects \a m_listeners. - std::vector<lldb::ListenerSP> m_hijacking_listeners; // A simple mechanism - // to intercept events - // from a broadcaster - std::vector<uint32_t> m_hijacking_masks; // At some point we may want to - // have a stack or Listener - // collections, but for now this is just for private hijacking. + /// The broadcaster that this implements. + Broadcaster &m_broadcaster; + + /// Optionally define event names for readability and logging for each + /// event bit. + event_names_map m_event_names; + + /// A list of Listener / event_mask pairs that are listening to this + /// broadcaster. + collection m_listeners; + + /// A mutex that protects \a m_listeners. + std::recursive_mutex m_listeners_mutex; + + /// A simple mechanism to intercept events from a broadcaster + std::vector<lldb::ListenerSP> m_hijacking_listeners; + + /// At some point we may want to have a stack or Listener collections, but + /// for now this is just for private hijacking. + std::vector<uint32_t> m_hijacking_masks; private: - //------------------------------------------------------------------ - // For Broadcaster only - //------------------------------------------------------------------ DISALLOW_COPY_AND_ASSIGN(BroadcasterImpl); }; @@ -577,18 +542,13 @@ protected: const char *GetHijackingListenerName() { return m_broadcaster_sp->GetHijackingListenerName(); } - //------------------------------------------------------------------ - // Classes that inherit from Broadcaster can see and modify these - //------------------------------------------------------------------ private: - //------------------------------------------------------------------ - // For Broadcaster only - //------------------------------------------------------------------ BroadcasterImplSP m_broadcaster_sp; lldb::BroadcasterManagerSP m_manager_sp; - const ConstString - m_broadcaster_name; ///< The name of this broadcaster object. + + /// The name of this broadcaster object. + const ConstString m_broadcaster_name; DISALLOW_COPY_AND_ASSIGN(Broadcaster); }; |