1 | //===-- Communication.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_CORE_COMMUNICATION_H |
10 | #define LLDB_CORE_COMMUNICATION_H |
11 | |
12 | #include "lldb/Utility/Timeout.h" |
13 | #include "lldb/lldb-defines.h" |
14 | #include "lldb/lldb-enumerations.h" |
15 | #include "lldb/lldb-forward.h" |
16 | #include "lldb/lldb-types.h" |
17 | |
18 | #include <mutex> |
19 | #include <string> |
20 | |
21 | namespace lldb_private { |
22 | class Connection; |
23 | class ConstString; |
24 | class Status; |
25 | |
26 | /// \class Communication Communication.h "lldb/Core/Communication.h" An |
27 | /// abstract communications class. |
28 | /// |
29 | /// Communication is an class that handles data communication between two data |
30 | /// sources. It uses a Connection class to do the real communication. This |
31 | /// approach has a couple of advantages: it allows a single instance of this |
32 | /// class to be used even though its connection can change. Connections could |
33 | /// negotiate for different connections based on abilities like starting with |
34 | /// Bluetooth and negotiating up to WiFi if available. |
35 | /// |
36 | /// When using this class, all reads and writes happen synchronously on the |
37 | /// calling thread. There is also a ThreadedCommunication class that supports |
38 | /// multi-threaded mode. |
39 | class Communication { |
40 | public: |
41 | /// Construct the Communication object. |
42 | Communication(); |
43 | |
44 | /// Destructor. |
45 | /// |
46 | /// The destructor is virtual since this class gets subclassed. |
47 | virtual ~Communication(); |
48 | |
49 | virtual void Clear(); |
50 | |
51 | /// Connect using the current connection by passing \a url to its connect |
52 | /// function. string. |
53 | /// |
54 | /// \param[in] url |
55 | /// A string that contains all information needed by the |
56 | /// subclass to connect to another client. |
57 | /// |
58 | /// \return |
59 | /// \b True if the connect succeeded, \b false otherwise. The |
60 | /// internal error object should be filled in with an |
61 | /// appropriate value based on the result of this function. |
62 | /// |
63 | /// \see Status& Communication::GetError (); |
64 | /// \see bool Connection::Connect (const char *url); |
65 | lldb::ConnectionStatus Connect(const char *url, Status *error_ptr); |
66 | |
67 | /// Disconnect the communications connection if one is currently connected. |
68 | /// |
69 | /// \return |
70 | /// \b True if the disconnect succeeded, \b false otherwise. The |
71 | /// internal error object should be filled in with an |
72 | /// appropriate value based on the result of this function. |
73 | /// |
74 | /// \see Status& Communication::GetError (); |
75 | /// \see bool Connection::Disconnect (); |
76 | virtual lldb::ConnectionStatus Disconnect(Status *error_ptr = nullptr); |
77 | |
78 | /// Check if the connection is valid. |
79 | /// |
80 | /// \return |
81 | /// \b True if this object is currently connected, \b false |
82 | /// otherwise. |
83 | bool IsConnected() const; |
84 | |
85 | bool HasConnection() const; |
86 | |
87 | lldb_private::Connection *GetConnection() { return m_connection_sp.get(); } |
88 | |
89 | /// Read bytes from the current connection. |
90 | /// |
91 | /// If no read thread is running, this function call the connection's |
92 | /// Connection::Read(...) function to get any available. |
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 | /// A timeout value or std::nullopt for no timeout. |
104 | /// |
105 | /// \return |
106 | /// The number of bytes actually read. |
107 | /// |
108 | /// \see size_t Connection::Read (void *, size_t); |
109 | virtual size_t Read(void *dst, size_t dst_len, |
110 | const Timeout<std::micro> &timeout, |
111 | lldb::ConnectionStatus &status, Status *error_ptr); |
112 | |
113 | /// The actual write function that attempts to write to the communications |
114 | /// protocol. |
115 | /// |
116 | /// Subclasses must override this function. |
117 | /// |
118 | /// \param[in] src |
119 | /// A source buffer that must be at least \a src_len bytes |
120 | /// long. |
121 | /// |
122 | /// \param[in] src_len |
123 | /// The number of bytes to attempt to write, and also the |
124 | /// number of bytes are currently available in \a src. |
125 | /// |
126 | /// \return |
127 | /// The number of bytes actually Written. |
128 | size_t Write(const void *src, size_t src_len, lldb::ConnectionStatus &status, |
129 | Status *error_ptr); |
130 | |
131 | /// Repeatedly attempt writing until either \a src_len bytes are written |
132 | /// or a permanent failure occurs. |
133 | /// |
134 | /// \param[in] src |
135 | /// A source buffer that must be at least \a src_len bytes |
136 | /// long. |
137 | /// |
138 | /// \param[in] src_len |
139 | /// The number of bytes to attempt to write, and also the |
140 | /// number of bytes are currently available in \a src. |
141 | /// |
142 | /// \return |
143 | /// The number of bytes actually Written. |
144 | size_t WriteAll(const void *src, size_t src_len, |
145 | lldb::ConnectionStatus &status, Status *error_ptr); |
146 | |
147 | /// Sets the connection that it to be used by this class. |
148 | /// |
149 | /// By making a communication class that uses different connections it |
150 | /// allows a single communication interface to negotiate and change its |
151 | /// connection without any interruption to the client. It also allows the |
152 | /// Communication class to be subclassed for packet based communication. |
153 | /// |
154 | /// \param[in] connection |
155 | /// A connection that this class will own and destroy. |
156 | /// |
157 | /// \see |
158 | /// class Connection |
159 | virtual void SetConnection(std::unique_ptr<Connection> connection); |
160 | |
161 | static std::string ConnectionStatusAsString(lldb::ConnectionStatus status); |
162 | |
163 | bool GetCloseOnEOF() const { return m_close_on_eof; } |
164 | |
165 | void SetCloseOnEOF(bool b) { m_close_on_eof = b; } |
166 | |
167 | protected: |
168 | lldb::ConnectionSP m_connection_sp; ///< The connection that is current in use |
169 | ///by this communications class. |
170 | std::mutex |
171 | m_write_mutex; ///< Don't let multiple threads write at the same time... |
172 | bool m_close_on_eof; |
173 | |
174 | size_t ReadFromConnection(void *dst, size_t dst_len, |
175 | const Timeout<std::micro> &timeout, |
176 | lldb::ConnectionStatus &status, Status *error_ptr); |
177 | |
178 | private: |
179 | Communication(const Communication &) = delete; |
180 | const Communication &operator=(const Communication &) = delete; |
181 | }; |
182 | |
183 | } // namespace lldb_private |
184 | |
185 | #endif // LLDB_CORE_COMMUNICATION_H |
186 | |