diff options
Diffstat (limited to 'include/lldb/Core/Communication.h')
| -rw-r--r-- | include/lldb/Core/Communication.h | 116 |
1 files changed, 38 insertions, 78 deletions
diff --git a/include/lldb/Core/Communication.h b/include/lldb/Core/Communication.h index f129b8f879d0..901b8fdb8c8b 100644 --- a/include/lldb/Core/Communication.h +++ b/include/lldb/Core/Communication.h @@ -1,9 +1,8 @@ //===-- Communication.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 // //===----------------------------------------------------------------------===// @@ -28,18 +27,10 @@ namespace lldb_private { class Connection; -} -namespace lldb_private { class ConstString; -} -namespace lldb_private { class Status; -} - -namespace lldb_private { -//---------------------------------------------------------------------- -/// @class Communication Communication.h "lldb/Core/Communication.h" An +/// \class Communication Communication.h "lldb/Core/Communication.h" An /// abstract communications class. /// /// Communication is an class that handles data communication between two data @@ -60,8 +51,8 @@ namespace lldb_private { /// "eBroadcastBit" below). /// /// There are two modes in which communications can occur: -/// @li single-threaded -/// @li multi-threaded +/// \li single-threaded +/// \li multi-threaded /// /// In single-threaded mode, all reads and writes happen synchronously on the /// calling thread. @@ -90,7 +81,6 @@ namespace lldb_private { /// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also /// post a \b eBroadcastBitReadThreadShouldExit event to this object which /// will cause the read thread to exit. -//---------------------------------------------------------------------- class Communication : public Broadcaster { public: FLAGS_ANONYMOUS_ENUM(){ @@ -116,72 +106,61 @@ public: typedef void (*ReadThreadBytesReceived)(void *baton, const void *src, size_t src_len); - //------------------------------------------------------------------ /// Construct the Communication object with the specified name for the /// Broadcaster that this object inherits from. /// - /// @param[in] broadcaster_name + /// \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. - //------------------------------------------------------------------ Communication(const char *broadcaster_name); - //------------------------------------------------------------------ /// Destructor. /// /// The destructor is virtual since this class gets subclassed. - //------------------------------------------------------------------ ~Communication() override; void Clear(); - //------------------------------------------------------------------ /// Connect using the current connection by passing \a url to its connect /// function. string. /// - /// @param[in] url + /// \param[in] url /// A string that contains all information needed by the /// subclass to connect to another client. /// - /// @return + /// \return /// \b True if the connect 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::Connect (const char *url); - //------------------------------------------------------------------ + /// \see Status& Communication::GetError (); + /// \see bool Connection::Connect (const char *url); lldb::ConnectionStatus Connect(const char *url, Status *error_ptr); - //------------------------------------------------------------------ /// Disconnect the communications connection if one is currently connected. /// - /// @return + /// \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 (); - //------------------------------------------------------------------ + /// \see Status& Communication::GetError (); + /// \see bool Connection::Disconnect (); lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr); - //------------------------------------------------------------------ /// Check if the connection is valid. /// - /// @return + /// \return /// \b True if this object is currently connected, \b false /// otherwise. - //------------------------------------------------------------------ bool IsConnected() const; bool HasConnection() const; lldb_private::Connection *GetConnection() { return m_connection_sp.get(); } - //------------------------------------------------------------------ /// Read bytes from the current connection. /// /// If no read thread is running, this function call the connection's @@ -194,46 +173,42 @@ public: /// event. If this function consumes all of the bytes in the cache, it will /// reset the \a eBroadcastBitReadThreadGotBytes event bit. /// - /// @param[in] dst + /// \param[in] dst /// A destination buffer that must be at least \a dst_len bytes /// long. /// - /// @param[in] dst_len + /// \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 + /// \param[in] timeout /// A timeout value or llvm::None for no timeout. /// - /// @return + /// \return /// The number of bytes actually read. /// - /// @see size_t Connection::Read (void *, size_t); - //------------------------------------------------------------------ + /// \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); - //------------------------------------------------------------------ /// The actual write function that attempts to write to the communications /// protocol. /// /// Subclasses must override this function. /// - /// @param[in] src + /// \param[in] src /// A source buffer that must be at least \a src_len bytes /// long. /// - /// @param[in] src_len + /// \param[in] src_len /// The number of bytes to attempt to write, and also the /// number of bytes are currently available in \a src. /// - /// @return + /// \return /// The number of bytes actually Written. - //------------------------------------------------------------------ size_t Write(const void *src, size_t src_len, lldb::ConnectionStatus &status, Status *error_ptr); - //------------------------------------------------------------------ /// Sets the connection that it to be used by this class. /// /// By making a communication class that uses different connections it @@ -241,15 +216,13 @@ public: /// connection without any interruption to the client. It also allows the /// Communication class to be subclassed for packet based communication. /// - /// @param[in] connection + /// \param[in] connection /// A connection that this class will own and destroy. /// - /// @see + /// \see /// class Connection - //------------------------------------------------------------------ void SetConnection(Connection *connection); - //------------------------------------------------------------------ /// Starts a read thread whose sole purpose it to read bytes from the /// current connection. This function will call connection's read function: /// @@ -265,60 +238,51 @@ public: /// default action of caching the bytes and broadcasting a \b /// eBroadcastBitReadThreadGotBytes event. /// - /// @return + /// \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, + /// \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 + /// \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 + /// \return /// \b True if the read thread is running, \b false otherwise. - //------------------------------------------------------------------ bool ReadThreadIsRunning(); - //------------------------------------------------------------------ /// The static 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 + /// \param[in] comm_ptr /// A pointer to an instance of this class. /// - /// @return + /// \return /// \b NULL. /// - /// @see void Communication::ReadThreadGotBytes (const uint8_t *, size_t); - //------------------------------------------------------------------ + /// \see void Communication::ReadThreadGotBytes (const uint8_t *, size_t); static lldb::thread_result_t ReadThread(lldb::thread_arg_t comm_ptr); 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 const char *ConnectionStatusAsCString(lldb::ConnectionStatus status); @@ -355,7 +319,6 @@ protected: const Timeout<std::micro> &timeout, lldb::ConnectionStatus &status, Status *error_ptr); - //------------------------------------------------------------------ /// 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. @@ -368,34 +331,31 @@ protected: /// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast /// to false. /// - /// @param[in] src + /// \param[in] src /// A source buffer that must be at least \a src_len bytes /// long. /// - /// @param[in] src_len + /// \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 + /// \param[in] dst /// A destination buffer that must be at least \a dst_len bytes /// long. /// - /// @param[in] dst_len + /// \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 + /// \return /// The number of bytes extracted from the data cache. - //------------------------------------------------------------------ size_t GetCachedBytes(void *dst, size_t dst_len); private: |