LLDB mainline
Communication.h
Go to the documentation of this file.
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
13#include "lldb/lldb-defines.h"
15#include "lldb/lldb-forward.h"
16#include "lldb/lldb-types.h"
17
18#include <mutex>
19#include <string>
20
21namespace lldb_private {
22class Connection;
23class ConstString;
24class 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.
40public:
41 /// Construct the Communication object.
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
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
167protected:
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...
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
178private:
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
An abstract communications class.
Definition: Communication.h:39
size_t ReadFromConnection(void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)
virtual size_t Read(void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)
Read bytes from the current connection.
lldb::ConnectionSP m_connection_sp
The connection that is current in use by this communications class.
lldb::ConnectionStatus Connect(const char *url, Status *error_ptr)
Connect using the current connection by passing url to its connect function.
bool IsConnected() const
Check if the connection is valid.
virtual void SetConnection(std::unique_ptr< Connection > connection)
Sets the connection that it to be used by this class.
virtual ~Communication()
Destructor.
size_t WriteAll(const void *src, size_t src_len, lldb::ConnectionStatus &status, Status *error_ptr)
Repeatedly attempt writing until either src_len bytes are written or a permanent failure occurs.
Communication()
Construct the Communication object.
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr=nullptr)
Disconnect the communications connection if one is currently connected.
static std::string ConnectionStatusAsString(lldb::ConnectionStatus status)
lldb_private::Connection * GetConnection()
Definition: Communication.h:87
const Communication & operator=(const Communication &)=delete
size_t Write(const void *src, size_t src_len, lldb::ConnectionStatus &status, Status *error_ptr)
The actual write function that attempts to write to the communications protocol.
Communication(const Communication &)=delete
std::mutex m_write_mutex
Don't let multiple threads write at the same time...
A communication connection class.
Definition: Connection.h:41
An error handling class.
Definition: Status.h:44
A class that represents a running process on the host machine.
std::shared_ptr< lldb_private::Connection > ConnectionSP
Definition: lldb-forward.h:330
ConnectionStatus
Connection Status Types.