LLDB  mainline
Connection.h
Go to the documentation of this file.
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
lldb_private::Connection
Definition: Connection.h:41
lldb_private::Connection::~Connection
virtual ~Connection()
Virtual destructor since this class gets subclassed and handed to a Communication object.
lldb_private::Connection::GetURI
virtual std::string GetURI()=0
Returns a URI that describes this connection object.
lldb_private::Connection::InterruptRead
virtual bool InterruptRead()=0
Interrupts an ongoing Read() operation.
lldb-defines.h
lldb_private::Connection::Connect
virtual lldb::ConnectionStatus Connect(llvm::StringRef url, Status *error_ptr)=0
Connect using the connect string url.
lldb_private::Connection::Connection
Connection()=default
Default constructor.
lldb_private::Connection::Disconnect
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr)=0
Disconnect the communications connection if one is currently connected.
lldb_private::Connection::Write
virtual size_t Write(const void *dst, size_t dst_len, lldb::ConnectionStatus &status, Status *error_ptr)=0
The actual write function that attempts to write to the communications protocol.
lldb-enumerations.h
lldb::ConnectionStatus
ConnectionStatus
Connection Status Types.
Definition: lldb-enumerations.h:295
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
lldb_private::Connection::operator=
const Connection & operator=(const Connection &)=delete
lldb_private::Status
Definition: Status.h:44
lldb_private::Timeout
Definition: Connection.h:25
lldb-forward.h
lldb_private::Connection::Read
virtual size_t Read(void *dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status *error_ptr)=0
The read function that attempts to read from the connection.
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::Connection::IsConnected
virtual bool IsConnected() const =0
Check if the connection is valid.
lldb_private::Connection::GetReadObject
virtual lldb::IOObjectSP GetReadObject()
Returns the underlying IOObject used by the Connection.
Definition: Connection.h:174
lldb_private::LineStatus::Status
@ Status