contrib/llvm-project/lldb/include/lldb/Utility/Connection.h

   1 //===-- Connection.h --------------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef liblldb_Connection_h_
  10 #define liblldb_Connection_h_
  11
  12 #include "lldb/lldb-defines.h"
  13 #include "lldb/lldb-enumerations.h"
  14 #include "lldb/lldb-forward.h"
  15
  16 #include "llvm/ADT/StringRef.h"
  17
  18 #include <ratio>
  19 #include <string>
  20
  21 #include <stddef.h>
  22
  23 namespace lldb_private {
  24 class Status;
  25 template <typename Ratio> class Timeout;
  26 }
  27
  28 namespace lldb_private {
  29
  30 /// \class Connection Connection.h "lldb/Utility/Connection.h"
  31 /// A communication connection class.
  32 ///
  33 /// A class that implements that actual communication functions for
  34 /// connecting/disconnecting, reading/writing, and waiting for bytes to become
  35 /// available from a two way communication connection.
  36 ///
  37 /// This class is designed to only do very simple communication functions.
  38 /// Instances can be instantiated and given to a Communication class to
  39 /// perform communications where clients can listen for broadcasts, and
  40 /// perform other higher level communications.
  41 class Connection {
  42 public:
  43   /// Default constructor
  44   Connection() = default;
  45
  46   /// Virtual destructor since this class gets subclassed and handed to a
  47   /// Communication object.
  48   virtual ~Connection();
  49
  50   /// Connect using the connect string \a url.
  51   ///
  52   /// \param[in] url
  53   ///     A string that contains all information needed by the
  54   ///     subclass to connect to another client.
  55   ///
  56   /// \param[out] error_ptr
  57   ///     A pointer to an error object that should be given an
  58   ///     appropriate error value if this method returns false. This
  59   ///     value can be NULL if the error value should be ignored.
  60   ///
  61   /// \return
  62   ///     \b True if the connect succeeded, \b false otherwise. The
  63   ///     internal error object should be filled in with an
  64   ///     appropriate value based on the result of this function.
  65   ///
  66   /// \see Status& Communication::GetError ();
  67   virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
  68                                          Status *error_ptr) = 0;
  69
  70   /// Disconnect the communications connection if one is currently connected.
  71   ///
  72   /// \param[out] error_ptr
  73   ///     A pointer to an error object that should be given an
  74   ///     appropriate error value if this method returns false. This
  75   ///     value can be NULL if the error value should be ignored.
  76   ///
  77   /// \return
  78   ///     \b True if the disconnect succeeded, \b false otherwise. The
  79   ///     internal error object should be filled in with an
  80   ///     appropriate value based on the result of this function.
  81   ///
  82   /// \see Status& Communication::GetError ();
  83   virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
  84
  85   /// Check if the connection is valid.
  86   ///
  87   /// \return
  88   ///     \b True if this object is currently connected, \b false
  89   ///     otherwise.
  90   virtual bool IsConnected() const = 0;
  91
  92   /// The read function that attempts to read from the connection.
  93   ///
  94   /// \param[in] dst
  95   ///     A destination buffer that must be at least \a dst_len bytes
  96   ///     long.
  97   ///
  98   /// \param[in] dst_len
  99   ///     The number of bytes to attempt to read, and also the max
 100   ///     number of bytes that can be placed into \a dst.
 101   ///
 102   /// \param[in] timeout
 103   ///     The number of microseconds to wait for the data.
 104   ///
 105   /// \param[out] status
 106   ///     On return, indicates whether the call was successful or terminated
 107   ///     due to some error condition.
 108   ///
 109   /// \param[out] error_ptr
 110   ///     A pointer to an error object that should be given an
 111   ///     appropriate error value if this method returns zero. This
 112   ///     value can be NULL if the error value should be ignored.
 113   ///
 114   /// \return
 115   ///     The number of bytes actually read.
 116   ///
 117   /// \see size_t Communication::Read (void *, size_t, uint32_t);
 118   virtual size_t Read(void *dst, size_t dst_len,
 119                       const Timeout<std::micro> &timeout,
 120                       lldb::ConnectionStatus &status, Status *error_ptr) = 0;
 121
 122   /// The actual write function that attempts to write to the communications
 123   /// protocol.
 124   ///
 125   /// Subclasses must override this function.
 126   ///
 127   /// \param[in] dst
 128   ///     A desination buffer that must be at least \a dst_len bytes
 129   ///     long.
 130   ///
 131   /// \param[in] dst_len
 132   ///     The number of bytes to attempt to write, and also the
 133   ///     number of bytes are currently available in \a dst.
 134   ///
 135   /// \param[out] error_ptr
 136   ///     A pointer to an error object that should be given an
 137   ///     appropriate error value if this method returns zero. This
 138   ///     value can be NULL if the error value should be ignored.
 139   ///
 140   /// \return
 141   ///     The number of bytes actually Written.
 142   virtual size_t Write(const void *dst, size_t dst_len,
 143                        lldb::ConnectionStatus &status, Status *error_ptr) = 0;
 144
 145   /// Returns a URI that describes this connection object
 146   ///
 147   /// Subclasses may override this function.
 148   ///
 149   /// \return
 150   ///     Returns URI or an empty string if disconnecteds
 151   virtual std::string GetURI() = 0;
 152
 153   /// Interrupts an ongoing Read() operation.
 154   ///
 155   /// If there is an ongoing read operation in another thread, this operation
 156   /// return with status == eConnectionStatusInterrupted. Note that if there
 157   /// data waiting to be read and an interrupt request is issued, the Read()
 158   /// function will return the data immediately without processing the
 159   /// interrupt request (which will remain queued for the next Read()
 160   /// operation).
 161   ///
 162   /// \return
 163   ///     Returns true is the interrupt request was successful.
 164   virtual bool InterruptRead() = 0;
 165
 166   /// Returns the underlying IOObject used by the Connection.
 167   ///
 168   /// The IOObject can be used to wait for data to become available on the
 169   /// connection. If the Connection does not use IOObjects (and hence does not
 170   /// support waiting) this function should return a null pointer.
 171   ///
 172   /// \return
 173   ///     The underlying IOObject used for reading.
 174   virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); };
 175
 176 private:
 177   // For Connection only
 178   DISALLOW_COPY_AND_ASSIGN(Connection);
 179 };
 180
 181 } // namespace lldb_private
 182
 183 #endif // liblldb_Connection_h_