1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
| //===-- Connection.h --------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
#ifndef liblldb_Connection_h_
#define liblldb_Connection_h_
#include "lldb/lldb-defines.h"
#include "lldb/lldb-enumerations.h"
#include "lldb/lldb-forward.h"
#include "llvm/ADT/StringRef.h"
#include <ratio>
#include <string>
#include <stddef.h>
namespace lldb_private {
class Status;
template <typename Ratio> class Timeout;
}
namespace lldb_private {
/// \class Connection Connection.h "lldb/Utility/Connection.h"
/// A communication connection class.
///
/// A class that implements that actual communication functions for
/// connecting/disconnecting, reading/writing, and waiting for bytes to become
/// available from a two way communication connection.
///
/// This class is designed to only do very simple communication functions.
/// Instances can be instantiated and given to a Communication class to
/// perform communications where clients can listen for broadcasts, and
/// perform other higher level communications.
class Connection {
public:
/// Default constructor
Connection() = default;
/// Virtual destructor since this class gets subclassed and handed to a
/// Communication object.
virtual ~Connection();
/// Connect using the connect string \a url.
///
/// \param[in] url
/// A string that contains all information needed by the
/// subclass to connect to another client.
///
/// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns false. This
/// value can be NULL if the error value should be ignored.
///
/// \return
/// \b True if the connect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
/// \see Status& Communication::GetError ();
virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
Status *error_ptr) = 0;
/// Disconnect the communications connection if one is currently connected.
///
/// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns false. This
/// value can be NULL if the error value should be ignored.
///
/// \return
/// \b True if the disconnect succeeded, \b false otherwise. The
/// internal error object should be filled in with an
/// appropriate value based on the result of this function.
///
/// \see Status& Communication::GetError ();
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
/// Check if the connection is valid.
///
/// \return
/// \b True if this object is currently connected, \b false
/// otherwise.
virtual bool IsConnected() const = 0;
/// The read function that attempts to read from the connection.
///
/// \param[in] dst
/// A destination buffer that must be at least \a dst_len bytes
/// long.
///
/// \param[in] dst_len
/// The number of bytes to attempt to read, and also the max
/// number of bytes that can be placed into \a dst.
///
/// \param[in] timeout
/// The number of microseconds to wait for the data.
///
/// \param[out] status
/// On return, indicates whether the call was successful or terminated
/// due to some error condition.
///
/// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns zero. This
/// value can be NULL if the error value should be ignored.
///
/// \return
/// The number of bytes actually read.
///
/// \see size_t Communication::Read (void *, size_t, uint32_t);
virtual size_t Read(void *dst, size_t dst_len,
const Timeout<std::micro> &timeout,
lldb::ConnectionStatus &status, Status *error_ptr) = 0;
/// The actual write function that attempts to write to the communications
/// protocol.
///
/// Subclasses must override this function.
///
/// \param[in] dst
/// A desination buffer that must be at least \a dst_len bytes
/// long.
///
/// \param[in] dst_len
/// The number of bytes to attempt to write, and also the
/// number of bytes are currently available in \a dst.
///
/// \param[out] error_ptr
/// A pointer to an error object that should be given an
/// appropriate error value if this method returns zero. This
/// value can be NULL if the error value should be ignored.
///
/// \return
/// The number of bytes actually Written.
virtual size_t Write(const void *dst, size_t dst_len,
lldb::ConnectionStatus &status, Status *error_ptr) = 0;
/// Returns a URI that describes this connection object
///
/// Subclasses may override this function.
///
/// \return
/// Returns URI or an empty string if disconnecteds
virtual std::string GetURI() = 0;
/// Interrupts an ongoing Read() operation.
///
/// If there is an ongoing read operation in another thread, this operation
/// return with status == eConnectionStatusInterrupted. Note that if there
/// data waiting to be read and an interrupt request is issued, the Read()
/// function will return the data immediately without processing the
/// interrupt request (which will remain queued for the next Read()
/// operation).
///
/// \return
/// Returns true is the interrupt request was successful.
virtual bool InterruptRead() = 0;
/// Returns the underlying IOObject used by the Connection.
///
/// The IOObject can be used to wait for data to become available on the
/// connection. If the Connection does not use IOObjects (and hence does not
/// support waiting) this function should return a null pointer.
///
/// \return
/// The underlying IOObject used for reading.
virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
private:
// For Connection only
DISALLOW_COPY_AND_ASSIGN(Connection);
};
} // namespace lldb_private
#endif // liblldb_Connection_h_
|