Connection.h revision 320543 
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
24namespace lldb_private {
25class Status;
26}
27namespace lldb_private {
28template <typename Ratio> class Timeout;
29}
30
31namespace 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//----------------------------------------------------------------------
46class Connection {
47public:
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
203private:
204  //------------------------------------------------------------------
205  // For Connection only
206  //------------------------------------------------------------------
207  DISALLOW_COPY_AND_ASSIGN(Connection);
208};
209
210} // namespace lldb_private
211
212#endif // liblldb_Connection_h_
213