Coverage Report

Created: 2022-01-18 06:27

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Utility/Connection.h
Line
Count
Source (jump to first uncovered line)
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
5.40k
  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
0
  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