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 
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.
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 
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 llvm::None 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 
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...
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
lldb_private::Connection
Definition: Connection.h:41
lldb_private::Communication::SetCloseOnEOF
void SetCloseOnEOF(bool b)
Definition: Communication.h:165
lldb-defines.h
lldb_private::Communication::ConnectionStatusAsString
static std::string ConnectionStatusAsString(lldb::ConnectionStatus status)
Definition: Communication.cpp:147
lldb_private::Communication::m_write_mutex
std::mutex m_write_mutex
Don't let multiple threads write at the same time...
Definition: Communication.h:171
lldb_private::Communication::m_connection_sp
lldb::ConnectionSP m_connection_sp
The connection that is current in use by this communications class.
Definition: Communication.h:168
lldb_private::Communication::SetConnection
virtual void SetConnection(std::unique_ptr< Connection > connection)
Sets the connection that it to be used by this class.
Definition: Communication.cpp:141
lldb_private::Communication
Definition: Communication.h:39
lldb_private::Communication::WriteAll
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.
Definition: Communication.cpp:117
lldb_private::LLDBLog::Connection
@ Connection
lldb_private::Communication::ReadFromConnection
size_t ReadFromConnection(void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)
Definition: Communication.cpp:127
lldb_private::Communication::Communication
Communication()
Construct the Communication object.
Definition: Communication.cpp:29
lldb_private::Communication::Clear
virtual void Clear()
Definition: Communication.cpp:37
lldb-enumerations.h
lldb::ConnectionStatus
ConnectionStatus
Connection Status Types.
Definition: lldb-enumerations.h:296
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
lldb_private::Communication::Write
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.
Definition: Communication.cpp:98
lldb_private::Communication::~Communication
virtual ~Communication()
Destructor.
Definition: Communication.cpp:33
lldb_private::Communication::operator=
const Communication & operator=(const Communication &)=delete
lldb-types.h
lldb_private::Communication::Disconnect
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr=nullptr)
Disconnect the communications connection if one is currently connected.
Definition: Communication.cpp:55
lldb_private::Communication::HasConnection
bool HasConnection() const
Definition: Communication.cpp:82
lldb_private::Status
Definition: Status.h:44
lldb_private::Timeout< std::micro >
lldb_private::Communication::Read
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.
Definition: Communication.cpp:86
Timeout.h
lldb_private::Communication::IsConnected
bool IsConnected() const
Check if the connection is valid.
Definition: Communication.cpp:77
lldb_private::Communication::GetCloseOnEOF
bool GetCloseOnEOF() const
Definition: Communication.h:163
lldb-forward.h
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::Communication::GetConnection
lldb_private::Connection * GetConnection()
Definition: Communication.h:87
lldb_private::LineStatus::Status
@ Status
lldb_private::Communication::m_close_on_eof
bool m_close_on_eof
Definition: Communication.h:172
lldb_private::Communication::Connect
lldb::ConnectionStatus Connect(const char *url, Status *error_ptr)
Connect using the current connection by passing url to its connect function.
Definition: Communication.cpp:41