contrib/llvm/tools/lldb/include/lldb/Core/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 Error;
  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/Core/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();
  52
  53   //------------------------------------------------------------------
  54   /// Virtual destructor since this class gets subclassed and handed
  55   /// to a Communication object.
  56   //------------------------------------------------------------------
  57   virtual ~Connection();
  58
  59   static Connection *CreateDefaultConnection(const char *url);
  60
  61   //------------------------------------------------------------------
  62   /// Connect using the connect string \a url.
  63   ///
  64   /// @param[in] url
  65   ///     A string that contains all information needed by the
  66   ///     subclass to connect to another client.
  67   ///
  68   /// @param[out] error_ptr
  69   ///     A pointer to an error object that should be given an
  70   ///     appropriate error value if this method returns false. This
  71   ///     value can be NULL if the error value should be ignored.
  72   ///
  73   /// @return
  74   ///     \b True if the connect succeeded, \b false otherwise. The
  75   ///     internal error object should be filled in with an
  76   ///     appropriate value based on the result of this function.
  77   ///
  78   /// @see Error& Communication::GetError ();
  79   //------------------------------------------------------------------
  80   virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
  81                                          Error *error_ptr) = 0;
  82
  83   //------------------------------------------------------------------
  84   /// Disconnect the communications connection if one is currently
  85   /// connected.
  86   ///
  87   /// @param[out] error_ptr
  88   ///     A pointer to an error object that should be given an
  89   ///     appropriate error value if this method returns false. This
  90   ///     value can be NULL if the error value should be ignored.
  91   ///
  92   /// @return
  93   ///     \b True if the disconnect succeeded, \b false otherwise. The
  94   ///     internal error object should be filled in with an
  95   ///     appropriate value based on the result of this function.
  96   ///
  97   /// @see Error& Communication::GetError ();
  98   //------------------------------------------------------------------
  99   virtual lldb::ConnectionStatus Disconnect(Error *error_ptr) = 0;
 100
 101   //------------------------------------------------------------------
 102   /// Check if the connection is valid.
 103   ///
 104   /// @return
 105   ///     \b True if this object is currently connected, \b false
 106   ///     otherwise.
 107   //------------------------------------------------------------------
 108   virtual bool IsConnected() const = 0;
 109
 110   //------------------------------------------------------------------
 111   /// The read function that attempts to read from the connection.
 112   ///
 113   /// @param[in] dst
 114   ///     A destination buffer that must be at least \a dst_len bytes
 115   ///     long.
 116   ///
 117   /// @param[in] dst_len
 118   ///     The number of bytes to attempt to read, and also the max
 119   ///     number of bytes that can be placed into \a dst.
 120   ///
 121   /// @param[in] timeout
 122   ///     The number of microseconds to wait for the data.
 123   ///
 124   /// @param[out] status
 125   ///     On return, indicates whether the call was successful or terminated
 126   ///     due to some error condition.
 127   ///
 128   /// @param[out] error_ptr
 129   ///     A pointer to an error object that should be given an
 130   ///     appropriate error value if this method returns zero. This
 131   ///     value can be NULL if the error value should be ignored.
 132   ///
 133   /// @return
 134   ///     The number of bytes actually read.
 135   ///
 136   /// @see size_t Communication::Read (void *, size_t, uint32_t);
 137   //------------------------------------------------------------------
 138   virtual size_t Read(void *dst, size_t dst_len,
 139                       const Timeout<std::micro> &timeout,
 140                       lldb::ConnectionStatus &status, Error *error_ptr) = 0;
 141
 142   //------------------------------------------------------------------
 143   /// The actual write function that attempts to write to the
 144   /// communications protocol.
 145   ///
 146   /// Subclasses must override this function.
 147   ///
 148   /// @param[in] dst
 149   ///     A desination buffer that must be at least \a dst_len bytes
 150   ///     long.
 151   ///
 152   /// @param[in] dst_len
 153   ///     The number of bytes to attempt to write, and also the
 154   ///     number of bytes are currently available in \a dst.
 155   ///
 156   /// @param[out] error_ptr
 157   ///     A pointer to an error object that should be given an
 158   ///     appropriate error value if this method returns zero. This
 159   ///     value can be NULL if the error value should be ignored.
 160   ///
 161   /// @return
 162   ///     The number of bytes actually Written.
 163   //------------------------------------------------------------------
 164   virtual size_t Write(const void *dst, size_t dst_len,
 165                        lldb::ConnectionStatus &status, Error *error_ptr) = 0;
 166
 167   //------------------------------------------------------------------
 168   /// Returns a URI that describes this connection object
 169   ///
 170   /// Subclasses may override this function.
 171   ///
 172   /// @return
 173   ///     Returns URI or an empty string if disconnecteds
 174   //------------------------------------------------------------------
 175   virtual std::string GetURI() = 0;
 176
 177   //------------------------------------------------------------------
 178   /// Interrupts an ongoing Read() operation.
 179   ///
 180   /// If there is an ongoing read operation in another thread, this operation
 181   /// return with status == eConnectionStatusInterrupted. Note that if there
 182   /// data waiting to be read and an interrupt request is issued, the Read()
 183   /// function will return the data immediately without processing the
 184   /// interrupt request (which will remain queued for the next Read()
 185   /// operation).
 186   ///
 187   /// @return
 188   ///     Returns true is the interrupt request was successful.
 189   //------------------------------------------------------------------
 190   virtual bool InterruptRead() = 0;
 191
 192   //------------------------------------------------------------------
 193   /// Returns the underlying IOObject used by the Connection.
 194   ///
 195   /// The IOObject can be used to wait for data to become available
 196   /// on the connection. If the Connection does not use IOObjects (and
 197   /// hence does not support waiting) this function should return a
 198   /// null pointer.
 199   ///
 200   /// @return
 201   ///     The underlying IOObject used for reading.
 202   //------------------------------------------------------------------
 203   virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
 204
 205 private:
 206   //------------------------------------------------------------------
 207   // For Connection only
 208   //------------------------------------------------------------------
 209   DISALLOW_COPY_AND_ASSIGN(Connection);
 210 };
 211
 212 } // namespace lldb_private
 213
 214 #endif // liblldb_Connection_h_