contrib/llvm/tools/lldb/include/lldb/Utility/Connection.h

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