xref: /openbsd-src/gnu/llvm/lldb/include/lldb/Core/ThreadedCommunication.h (revision f6aab3d83b51b91c24247ad2c2573574de475a82)

//===-- 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 std::nullopt 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