Communication.h

Go to the documentation of this file.

//===-- Communication.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_COMMUNICATION_H
#define LLDB_CORE_COMMUNICATION_H
 
#include "lldb/Utility/Timeout.h"
#include "lldb/lldb-defines.h"
#include "lldb/lldb-enumerations.h"
#include "lldb/lldb-forward.h"
#include "lldb/lldb-types.h"
 
#include <mutex>
#include <string>
 
namespace lldb_private {
class Connection;
class Status;
 
/// \class Communication Communication.h "lldb/Core/Communication.h" An
/// abstract communications class.
///
/// Communication is an class that handles data communication between two data
/// sources. It uses a Connection class to do the real communication. This
/// approach has a couple of advantages: it allows a single instance of this
/// class to be used even though its connection can change. Connections could
/// negotiate for different connections based on abilities like starting with
/// Bluetooth and negotiating up to WiFi if available.
///
/// When using this class, all reads and writes happen synchronously on the
/// calling thread. There is also a ThreadedCommunication class that supports
/// multi-threaded mode.
class Communication {
public:
  /// Construct the Communication object.
  Communication();
 
  /// Destructor.
  ///
  /// The destructor is virtual since this class gets subclassed.
  virtual ~Communication();
 
  virtual void Clear();
 
  /// Connect using the current connection by passing \a url to its connect
  /// function. string.
  ///
  /// \param[in] url
  ///     A string that contains all information needed by the
  ///     subclass to connect to another client.
  ///
  /// \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);
  lldb::ConnectionStatus Connect(const char *url, Status *error_ptr);
 
  /// 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 ();
  virtual lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr);
 
  /// Check if the connection is valid.
  ///
  /// \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
  /// Connection::Read(...) function to get any 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, 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);
  virtual 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
  ///     A source buffer that must be at least \a src_len bytes
  ///     long.
  ///
  /// \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
  ///     The number of bytes actually Written.
  size_t Write(const void *src, size_t src_len, lldb::ConnectionStatus &status,
               Status *error_ptr);
 
  /// Repeatedly attempt writing until either \a src_len bytes are written
  /// or a permanent failure occurs.
  ///
  /// \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 attempt to write, and also the
  ///     number of bytes are currently available in \a src.
  ///
  /// \return
  ///     The number of bytes actually Written.
  size_t WriteAll(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
  /// 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
  virtual void SetConnection(std::unique_ptr<Connection> connection);
 
  static std::string ConnectionStatusAsString(lldb::ConnectionStatus status);
 
  bool GetCloseOnEOF() const { return m_close_on_eof; }
 
  void SetCloseOnEOF(bool b) { m_close_on_eof = b; }
 
protected:
  lldb::ConnectionSP m_connection_sp; ///< The connection that is current in use
                                      ///by this communications class.
  std::mutex
      m_write_mutex; ///< Don't let multiple threads write at the same time...
  bool m_close_on_eof;
 
  size_t ReadFromConnection(void *dst, size_t dst_len,
                            const Timeout<std::micro> &timeout,
                            lldb::ConnectionStatus &status, Status *error_ptr);
 
private:
  Communication(const Communication &) = delete;
  const Communication &operator=(const Communication &) = delete;
};
 
} // namespace lldb_private
 
#endif // LLDB_CORE_COMMUNICATION_H