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 LLDB_UTILITY_CONNECTION_H 10 #define LLDB_UTILITY_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 <cstddef> 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 destination 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 Connection(const Connection &) = delete; 179 const Connection &operator=(const Connection &) = delete; 180 }; 181 182 } // namespace lldb_private 183 184 #endif // LLDB_UTILITY_CONNECTION_H 185