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 | 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 | 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 |
185 | |