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"
14 #include "lldb/lldb-enumerations.h"
15 #include "lldb/lldb-forward.h"
16 
17 #include "llvm/ADT/StringRef.h"
18 
19 #include <ratio>
20 #include <string>
21 
22 #include <stddef.h>
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 /// A communication connection class.
36 ///
37 /// A class that implements that actual communication functions for
38 /// connecting/disconnecting, reading/writing, and waiting for bytes to become
39 /// available from a two way communication connection.
40 ///
41 /// This class is designed to only do very simple communication functions.
42 /// Instances can be instantiated and given to a Communication class to
43 /// perform communications where clients can listen for broadcasts, and
44 /// 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 to a
55   /// 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 connected.
83   ///
84   /// @param[out] error_ptr
85   ///     A pointer to an error object that should be given an
86   ///     appropriate error value if this method returns false. This
87   ///     value can be NULL if the error value should be ignored.
88   ///
89   /// @return
90   ///     \b True if the disconnect succeeded, \b false otherwise. The
91   ///     internal error object should be filled in with an
92   ///     appropriate value based on the result of this function.
93   ///
94   /// @see Status& Communication::GetError ();
95   //------------------------------------------------------------------
96   virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
97 
98   //------------------------------------------------------------------
99   /// Check if the connection is valid.
100   ///
101   /// @return
102   ///     \b True if this object is currently connected, \b false
103   ///     otherwise.
104   //------------------------------------------------------------------
105   virtual bool IsConnected() const = 0;
106 
107   //------------------------------------------------------------------
108   /// The read function that attempts to read from the connection.
109   ///
110   /// @param[in] dst
111   ///     A destination buffer that must be at least \a dst_len bytes
112   ///     long.
113   ///
114   /// @param[in] dst_len
115   ///     The number of bytes to attempt to read, and also the max
116   ///     number of bytes that can be placed into \a dst.
117   ///
118   /// @param[in] timeout
119   ///     The number of microseconds to wait for the data.
120   ///
121   /// @param[out] status
122   ///     On return, indicates whether the call was successful or terminated
123   ///     due to some error condition.
124   ///
125   /// @param[out] error_ptr
126   ///     A pointer to an error object that should be given an
127   ///     appropriate error value if this method returns zero. This
128   ///     value can be NULL if the error value should be ignored.
129   ///
130   /// @return
131   ///     The number of bytes actually read.
132   ///
133   /// @see size_t Communication::Read (void *, size_t, uint32_t);
134   //------------------------------------------------------------------
135   virtual size_t Read(void *dst, size_t dst_len,
136                       const Timeout<std::micro> &timeout,
137                       lldb::ConnectionStatus &status, Status *error_ptr) = 0;
138 
139   //------------------------------------------------------------------
140   /// The actual write function that attempts to write to the communications
141   /// protocol.
142   ///
143   /// Subclasses must override this function.
144   ///
145   /// @param[in] dst
146   ///     A desination buffer that must be at least \a dst_len bytes
147   ///     long.
148   ///
149   /// @param[in] dst_len
150   ///     The number of bytes to attempt to write, and also the
151   ///     number of bytes are currently available in \a dst.
152   ///
153   /// @param[out] error_ptr
154   ///     A pointer to an error object that should be given an
155   ///     appropriate error value if this method returns zero. This
156   ///     value can be NULL if the error value should be ignored.
157   ///
158   /// @return
159   ///     The number of bytes actually Written.
160   //------------------------------------------------------------------
161   virtual size_t Write(const void *dst, size_t dst_len,
162                        lldb::ConnectionStatus &status, Status *error_ptr) = 0;
163 
164   //------------------------------------------------------------------
165   /// Returns a URI that describes this connection object
166   ///
167   /// Subclasses may override this function.
168   ///
169   /// @return
170   ///     Returns URI or an empty string if disconnecteds
171   //------------------------------------------------------------------
172   virtual std::string GetURI() = 0;
173 
174   //------------------------------------------------------------------
175   /// Interrupts an ongoing Read() operation.
176   ///
177   /// If there is an ongoing read operation in another thread, this operation
178   /// return with status == eConnectionStatusInterrupted. Note that if there
179   /// data waiting to be read and an interrupt request is issued, the Read()
180   /// function will return the data immediately without processing the
181   /// interrupt request (which will remain queued for the next Read()
182   /// operation).
183   ///
184   /// @return
185   ///     Returns true is the interrupt request was successful.
186   //------------------------------------------------------------------
187   virtual bool InterruptRead() = 0;
188 
189   //------------------------------------------------------------------
190   /// Returns the underlying IOObject used by the Connection.
191   ///
192   /// The IOObject can be used to wait for data to become available on the
193   /// connection. If the Connection does not use IOObjects (and hence does not
194   /// support waiting) this function should return a null pointer.
195   ///
196   /// @return
197   ///     The underlying IOObject used for reading.
198   //------------------------------------------------------------------
GetReadObject()199   virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
200 
201 private:
202   //------------------------------------------------------------------
203   // For Connection only
204   //------------------------------------------------------------------
205   DISALLOW_COPY_AND_ASSIGN(Connection);
206 };
207 
208 } // namespace lldb_private
209 
210 #endif // liblldb_Connection_h_
211