aarch64/usr/include/lldb/Core/ThreadedCommunication.h - manifest_repos/toolchain - Git at Google

 //===-- ThreadedCommunication.h ---------------------------------*- C++ -*-===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//

 #ifndef LLDB_CORE_THREADEDCOMMUNICATION_H
 #define LLDB_CORE_THREADEDCOMMUNICATION_H

 #include "lldb/Core/Communication.h"
 #include "lldb/Host/HostThread.h"
 #include "lldb/Utility/Broadcaster.h"

 #include <atomic>
 #include <mutex>
 #include <string>

 #include <cstddef>
 #include <cstdint>

 namespace lldb_private {

 /// \class ThreadedCommunication ThreadedCommunication.h
 /// "lldb/Core/ThreadedCommunication.h" Variation of Communication that
 /// supports threaded reads.
 ///
 /// ThreadedCommunication enhances the base Communication class with support
 /// for multi-threaded mode.  In this mode, a read thread is spawned that
 /// continually reads data and caches any received bytes. To start the read
 /// thread clients call:
 ///
 ///     bool ThreadedCommunication::StartReadThread (Status *);
 ///
 /// If true is returned a read thread has been spawned that will continually
 /// execute a call to the pure virtual DoRead function:
 ///
 ///     size_t Communication::ReadFromConnection (void *, size_t, uint32_t);
 ///
 /// When bytes are received the data gets cached in \a m_bytes and this class
 /// will broadcast a \b eBroadcastBitReadThreadGotBytes event. Clients that
 /// want packet based communication should override AppendBytesToCache. The
 /// subclasses can choose to call the built in AppendBytesToCache with the \a
 /// broadcast parameter set to false. This will cause the \b
 /// eBroadcastBitReadThreadGotBytes event not get broadcast, and then the
 /// subclass can post a \b eBroadcastBitPacketAvailable event when a full
 /// packet of data has been received.
 ///
 /// If the connection is disconnected a \b eBroadcastBitDisconnected event
 /// gets broadcast. If the read thread exits a \b
 /// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also
 /// post a \b eBroadcastBitReadThreadShouldExit event to this object which
 /// will cause the read thread to exit.
 ///
 /// ThreadedCommunication inherits from Broadcaster which means it can be used
 /// in conjunction with Listener to wait for multiple broadcaster objects and
 /// multiple events from each of those objects. ThreadedCommunication defines a
 /// set of pre-defined event bits (see enumerations definitions that start with
 /// "eBroadcastBit" below).
 class ThreadedCommunication : public Communication, public Broadcaster {
   using Communication::Communication;

 public:
   FLAGS_ANONYMOUS_ENUM(){
       eBroadcastBitDisconnected =
           (1u << 0), ///< Sent when the communications connection is lost.
       eBroadcastBitReadThreadGotBytes =
           (1u << 1), ///< Sent by the read thread when bytes become available.
       eBroadcastBitReadThreadDidExit =
           (1u
            << 2), ///< Sent by the read thread when it exits to inform clients.
       eBroadcastBitReadThreadShouldExit =
           (1u << 3), ///< Sent by clients that need to cancel the read thread.
       eBroadcastBitPacketAvailable =
           (1u << 4), ///< Sent when data received makes a complete packet.
       eBroadcastBitNoMorePendingInput = (1u << 5), ///< Sent by the read thread
                                                    /// to indicate all pending
                                                    /// input has been processed.
   };

   typedef void (*ReadThreadBytesReceived)(void *baton, const void *src,
                                           size_t src_len);

   /// Construct the ThreadedCommunication object with the specified name for the
   /// Broadcaster that this object inherits from.
   ///
   /// \param[in] broadcaster_name
   ///     The name of the broadcaster object.  This name should be as
   ///     complete as possible to uniquely identify this object. The
   ///     broadcaster name can be updated after the connect function
   ///     is called.
   ThreadedCommunication(const char *broadcaster_name);

   /// Destructor.
   ///
   /// The destructor is virtual since this class gets subclassed.
   ~ThreadedCommunication() override;

   void Clear() override;

   /// Disconnect the communications connection if one is currently connected.
   ///
   /// \return
   ///     \b True if the disconnect succeeded, \b false otherwise. The
   ///     internal error object should be filled in with an
   ///     appropriate value based on the result of this function.
   ///
   /// \see Status& Communication::GetError ();
   /// \see bool Connection::Disconnect ();
   lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr) override;

   /// Read bytes from the current connection.
   ///
   /// If no read thread is running, this function call the connection's
   /// Connection::Read(...) function to get any available.
   ///
   /// If a read thread has been started, this function will check for any
   /// cached bytes that have already been read and return any currently
   /// available bytes. If no bytes are cached, it will wait for the bytes to
   /// become available by listening for the \a eBroadcastBitReadThreadGotBytes
   /// event. If this function consumes all of the bytes in the cache, it will
   /// reset the \a eBroadcastBitReadThreadGotBytes event bit.
   ///
   /// \param[in] dst
   ///     A destination buffer that must be at least \a dst_len bytes
   ///     long.
   ///
   /// \param[in] dst_len
   ///     The number of bytes to attempt to read, and also the max
   ///     number of bytes that can be placed into \a dst.
   ///
   /// \param[in] timeout
   ///     A timeout value or llvm::None for no timeout.
   ///
   /// \return
   ///     The number of bytes actually read.
   ///
   /// \see size_t Connection::Read (void *, size_t);
   size_t Read(void *dst, size_t dst_len, const Timeout<std::micro> &timeout,
               lldb::ConnectionStatus &status, Status *error_ptr) override;

   /// Sets the connection that it to be used by this class.
   ///
   /// By making a communication class that uses different connections it
   /// allows a single communication interface to negotiate and change its
   /// connection without any interruption to the client. It also allows the
   /// Communication class to be subclassed for packet based communication.
   ///
   /// \param[in] connection
   ///     A connection that this class will own and destroy.
   ///
   /// \see
   ///     class Connection
   void SetConnection(std::unique_ptr<Connection> connection) override;

   /// Starts a read thread whose sole purpose it to read bytes from the
   /// current connection. This function will call connection's read function:
   ///
   /// size_t Connection::Read (void *, size_t);
   ///
   /// When bytes are read and cached, this function will call:
   ///
   /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len,
   /// bool
   /// broadcast);
   ///
   /// Subclasses should override this function if they wish to override the
   /// default action of caching the bytes and broadcasting a \b
   /// eBroadcastBitReadThreadGotBytes event.
   ///
   /// \return
   ///     \b True if the read thread was successfully started, \b
   ///     false otherwise.
   ///
   /// \see size_t Connection::Read (void *, size_t);
   /// \see void Communication::AppendBytesToCache (const uint8_t * bytes,
   ///                                              size_t len, bool broadcast);
   virtual bool StartReadThread(Status *error_ptr = nullptr);

   /// Stops the read thread by cancelling it.
   ///
   /// \return
   ///     \b True if the read thread was successfully canceled, \b
   ///     false otherwise.
   virtual bool StopReadThread(Status *error_ptr = nullptr);

   virtual bool JoinReadThread(Status *error_ptr = nullptr);
   /// Checks if there is a currently running read thread.
   ///
   /// \return
   ///     \b True if the read thread is running, \b false otherwise.
   bool ReadThreadIsRunning();

   /// The read thread function. This function will call the "DoRead"
   /// function continuously and wait for data to become available. When data
   /// is received it will append the available data to the internal cache and
   /// broadcast a \b eBroadcastBitReadThreadGotBytes event.
   ///
   /// \param[in] comm_ptr
   ///     A pointer to an instance of this class.
   ///
   /// \return
   ///     \b NULL.
   ///
   /// \see void Communication::ReadThreadGotBytes (const uint8_t *, size_t);
   lldb::thread_result_t ReadThread();

   void SetReadThreadBytesReceivedCallback(ReadThreadBytesReceived callback,
                                           void *callback_baton);

   /// Wait for the read thread to process all outstanding data.
   ///
   /// After this function returns, the read thread has processed all data that
   /// has been waiting in the Connection queue.
   ///
   void SynchronizeWithReadThread();

   static ConstString &GetStaticBroadcasterClass();

   ConstString &GetBroadcasterClass() const override {
     return GetStaticBroadcasterClass();
   }

 protected:
   HostThread m_read_thread; ///< The read thread handle in case we need to
                             /// cancel the thread.
   std::atomic<bool> m_read_thread_enabled;
   std::atomic<bool> m_read_thread_did_exit;
   std::string
       m_bytes; ///< A buffer to cache bytes read in the ReadThread function.
   std::recursive_mutex m_bytes_mutex;   ///< A mutex to protect multi-threaded
                                         /// access to the cached bytes.
   lldb::ConnectionStatus m_pass_status; ///< Connection status passthrough
                                         /// from read thread.
   Status m_pass_error;                  ///< Error passthrough from read thread.
   std::mutex m_synchronize_mutex;
   ReadThreadBytesReceived m_callback;
   void *m_callback_baton;

   /// Append new bytes that get read from the read thread into the internal
   /// object byte cache. This will cause a \b eBroadcastBitReadThreadGotBytes
   /// event to be broadcast if \a broadcast is true.
   ///
   /// Subclasses can override this function in order to inspect the received
   /// data and check if a packet is available.
   ///
   /// Subclasses can also still call this function from the overridden method
   /// to allow the caching to correctly happen and suppress the broadcasting
   /// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast
   /// to false.
   ///
   /// \param[in] src
   ///     A source buffer that must be at least \a src_len bytes
   ///     long.
   ///
   /// \param[in] src_len
   ///     The number of bytes to append to the cache.
   virtual void AppendBytesToCache(const uint8_t *src, size_t src_len,
                                   bool broadcast,
                                   lldb::ConnectionStatus status);

   /// Get any available bytes from our data cache. If this call empties the
   /// data cache, the \b eBroadcastBitReadThreadGotBytes event will be reset
   /// to signify no more bytes are available.
   ///
   /// \param[in] dst
   ///     A destination buffer that must be at least \a dst_len bytes
   ///     long.
   ///
   /// \param[in] dst_len
   ///     The number of bytes to attempt to read from the cache,
   ///     and also the max number of bytes that can be placed into
   ///     \a dst.
   ///
   /// \return
   ///     The number of bytes extracted from the data cache.
   size_t GetCachedBytes(void *dst, size_t dst_len);

 private:
   ThreadedCommunication(const ThreadedCommunication &) = delete;
   const ThreadedCommunication &
   operator=(const ThreadedCommunication &) = delete;
 };

 } // namespace lldb_private

 #endif // LLDB_CORE_THREADEDCOMMUNICATION_H
	//===-- ThreadedCommunication.h ---------------------------------- C++ --===//
	//
	// 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
	//
	//===----------------------------------------------------------------------===//

	#ifndef LLDB_CORE_THREADEDCOMMUNICATION_H
	#define LLDB_CORE_THREADEDCOMMUNICATION_H

	#include "lldb/Core/Communication.h"
	#include "lldb/Host/HostThread.h"
	#include "lldb/Utility/Broadcaster.h"

	#include <atomic>
	#include <mutex>
	#include <string>

	#include <cstddef>
	#include <cstdint>

	namespace lldb_private {

	/// \class ThreadedCommunication ThreadedCommunication.h
	/// "lldb/Core/ThreadedCommunication.h" Variation of Communication that
	/// supports threaded reads.
	///
	/// ThreadedCommunication enhances the base Communication class with support
	/// for multi-threaded mode. In this mode, a read thread is spawned that
	/// continually reads data and caches any received bytes. To start the read
	/// thread clients call:
	///
	/// bool ThreadedCommunication::StartReadThread (Status *);
	///
	/// If true is returned a read thread has been spawned that will continually
	/// execute a call to the pure virtual DoRead function:
	///
	/// size_t Communication::ReadFromConnection (void *, size_t, uint32_t);
	///
	/// When bytes are received the data gets cached in \a m_bytes and this class
	/// will broadcast a \b eBroadcastBitReadThreadGotBytes event. Clients that
	/// want packet based communication should override AppendBytesToCache. The
	/// subclasses can choose to call the built in AppendBytesToCache with the \a
	/// broadcast parameter set to false. This will cause the \b
	/// eBroadcastBitReadThreadGotBytes event not get broadcast, and then the
	/// subclass can post a \b eBroadcastBitPacketAvailable event when a full
	/// packet of data has been received.
	///
	/// If the connection is disconnected a \b eBroadcastBitDisconnected event
	/// gets broadcast. If the read thread exits a \b
	/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also
	/// post a \b eBroadcastBitReadThreadShouldExit event to this object which
	/// will cause the read thread to exit.
	///
	/// ThreadedCommunication inherits from Broadcaster which means it can be used
	/// in conjunction with Listener to wait for multiple broadcaster objects and
	/// multiple events from each of those objects. ThreadedCommunication defines a
	/// set of pre-defined event bits (see enumerations definitions that start with
	/// "eBroadcastBit" below).
	class ThreadedCommunication : public Communication, public Broadcaster {
	using Communication::Communication;

	public:
	FLAGS_ANONYMOUS_ENUM(){
	eBroadcastBitDisconnected =
	(1u << 0), ///< Sent when the communications connection is lost.
	eBroadcastBitReadThreadGotBytes =
	(1u << 1), ///< Sent by the read thread when bytes become available.
	eBroadcastBitReadThreadDidExit =
	(1u
	<< 2), ///< Sent by the read thread when it exits to inform clients.
	eBroadcastBitReadThreadShouldExit =
	(1u << 3), ///< Sent by clients that need to cancel the read thread.
	eBroadcastBitPacketAvailable =
	(1u << 4), ///< Sent when data received makes a complete packet.
	eBroadcastBitNoMorePendingInput = (1u << 5), ///< Sent by the read thread
	/// to indicate all pending
	/// input has been processed.
	};

	typedef void (ReadThreadBytesReceived)(void baton, const void *src,
	size_t src_len);

	/// Construct the ThreadedCommunication object with the specified name for the
	/// Broadcaster that this object inherits from.
	///
	/// \param[in] broadcaster_name
	/// The name of the broadcaster object. This name should be as
	/// complete as possible to uniquely identify this object. The
	/// broadcaster name can be updated after the connect function
	/// is called.
	ThreadedCommunication(const char *broadcaster_name);

	/// Destructor.
	///
	/// The destructor is virtual since this class gets subclassed.
	~ThreadedCommunication() override;

	void Clear() override;

	/// Disconnect the communications connection if one is currently connected.
	///
	/// \return
	/// \b True if the disconnect succeeded, \b false otherwise. The
	/// internal error object should be filled in with an
	/// appropriate value based on the result of this function.
	///
	/// \see Status& Communication::GetError ();
	/// \see bool Connection::Disconnect ();
	lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr) override;

	/// Read bytes from the current connection.
	///
	/// If no read thread is running, this function call the connection's
	/// Connection::Read(...) function to get any available.
	///
	/// If a read thread has been started, this function will check for any
	/// cached bytes that have already been read and return any currently
	/// available bytes. If no bytes are cached, it will wait for the bytes to
	/// become available by listening for the \a eBroadcastBitReadThreadGotBytes
	/// event. If this function consumes all of the bytes in the cache, it will
	/// reset the \a eBroadcastBitReadThreadGotBytes event bit.
	///
	/// \param[in] dst
	/// A destination buffer that must be at least \a dst_len bytes
	/// long.
	///
	/// \param[in] dst_len
	/// The number of bytes to attempt to read, and also the max
	/// number of bytes that can be placed into \a dst.
	///
	/// \param[in] timeout
	/// A timeout value or llvm::None for no timeout.
	///
	/// \return
	/// The number of bytes actually read.
	///
	/// \see size_t Connection::Read (void *, size_t);
	size_t Read(void *dst, size_t dst_len, const Timeout<std::micro> &timeout,
	lldb::ConnectionStatus &status, Status *error_ptr) override;

	/// Sets the connection that it to be used by this class.
	///
	/// By making a communication class that uses different connections it
	/// allows a single communication interface to negotiate and change its
	/// connection without any interruption to the client. It also allows the
	/// Communication class to be subclassed for packet based communication.
	///
	/// \param[in] connection
	/// A connection that this class will own and destroy.
	///
	/// \see
	/// class Connection
	void SetConnection(std::unique_ptr<Connection> connection) override;

	/// Starts a read thread whose sole purpose it to read bytes from the
	/// current connection. This function will call connection's read function:
	///
	/// size_t Connection::Read (void *, size_t);
	///
	/// When bytes are read and cached, this function will call:
	///
	/// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len,
	/// bool
	/// broadcast);
	///
	/// Subclasses should override this function if they wish to override the
	/// default action of caching the bytes and broadcasting a \b
	/// eBroadcastBitReadThreadGotBytes event.
	///
	/// \return
	/// \b True if the read thread was successfully started, \b
	/// false otherwise.
	///
	/// \see size_t Connection::Read (void *, size_t);
	/// \see void Communication::AppendBytesToCache (const uint8_t * bytes,
	/// size_t len, bool broadcast);
	virtual bool StartReadThread(Status *error_ptr = nullptr);

	/// Stops the read thread by cancelling it.
	///
	/// \return
	/// \b True if the read thread was successfully canceled, \b
	/// false otherwise.
	virtual bool StopReadThread(Status *error_ptr = nullptr);

	virtual bool JoinReadThread(Status *error_ptr = nullptr);
	/// Checks if there is a currently running read thread.
	///
	/// \return
	/// \b True if the read thread is running, \b false otherwise.
	bool ReadThreadIsRunning();

	/// The read thread function. This function will call the "DoRead"
	/// function continuously and wait for data to become available. When data
	/// is received it will append the available data to the internal cache and
	/// broadcast a \b eBroadcastBitReadThreadGotBytes event.
	///
	/// \param[in] comm_ptr
	/// A pointer to an instance of this class.
	///
	/// \return
	/// \b NULL.
	///
	/// \see void Communication::ReadThreadGotBytes (const uint8_t *, size_t);
	lldb::thread_result_t ReadThread();

	void SetReadThreadBytesReceivedCallback(ReadThreadBytesReceived callback,
	void *callback_baton);

	/// Wait for the read thread to process all outstanding data.
	///
	/// After this function returns, the read thread has processed all data that
	/// has been waiting in the Connection queue.
	///
	void SynchronizeWithReadThread();

	static ConstString &GetStaticBroadcasterClass();

	ConstString &GetBroadcasterClass() const override {
	return GetStaticBroadcasterClass();
	}

	protected:
	HostThread m_read_thread; ///< The read thread handle in case we need to
	/// cancel the thread.
	std::atomic<bool> m_read_thread_enabled;
	std::atomic<bool> m_read_thread_did_exit;
	std::string
	m_bytes; ///< A buffer to cache bytes read in the ReadThread function.
	std::recursive_mutex m_bytes_mutex; ///< A mutex to protect multi-threaded
	/// access to the cached bytes.
	lldb::ConnectionStatus m_pass_status; ///< Connection status passthrough
	/// from read thread.
	Status m_pass_error; ///< Error passthrough from read thread.
	std::mutex m_synchronize_mutex;
	ReadThreadBytesReceived m_callback;
	void *m_callback_baton;

	/// Append new bytes that get read from the read thread into the internal
	/// object byte cache. This will cause a \b eBroadcastBitReadThreadGotBytes
	/// event to be broadcast if \a broadcast is true.
	///
	/// Subclasses can override this function in order to inspect the received
	/// data and check if a packet is available.
	///
	/// Subclasses can also still call this function from the overridden method
	/// to allow the caching to correctly happen and suppress the broadcasting
	/// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast
	/// to false.
	///
	/// \param[in] src
	/// A source buffer that must be at least \a src_len bytes
	/// long.
	///
	/// \param[in] src_len
	/// The number of bytes to append to the cache.
	virtual void AppendBytesToCache(const uint8_t *src, size_t src_len,
	bool broadcast,
	lldb::ConnectionStatus status);

	/// Get any available bytes from our data cache. If this call empties the
	/// data cache, the \b eBroadcastBitReadThreadGotBytes event will be reset
	/// to signify no more bytes are available.
	///
	/// \param[in] dst
	/// A destination buffer that must be at least \a dst_len bytes
	/// long.
	///
	/// \param[in] dst_len
	/// The number of bytes to attempt to read from the cache,
	/// and also the max number of bytes that can be placed into
	/// \a dst.
	///
	/// \return
	/// The number of bytes extracted from the data cache.
	size_t GetCachedBytes(void *dst, size_t dst_len);

	private:
	ThreadedCommunication(const ThreadedCommunication &) = delete;
	const ThreadedCommunication &
	operator=(const ThreadedCommunication &) = delete;
	};

	} // namespace lldb_private

	#endif // LLDB_CORE_THREADEDCOMMUNICATION_H