Connection.h revision 341825 
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/// 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//----------------------------------------------------------------------
46class Connection {
47public:
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  //------------------------------------------------------------------
199  virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
200
201private:
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