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 liblldb_Connection_h_
10 #define liblldb_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 <stddef.h>
22 
23 namespace lldb_private {
24 class Status;
25 }
26 namespace lldb_private {
27 template <typename Ratio> class Timeout;
28 }
29 
30 namespace lldb_private {
31 
32 /// \class Connection Connection.h "lldb/Utility/Connection.h"
33 /// A communication connection class.
34 ///
35 /// A class that implements that actual communication functions for
36 /// connecting/disconnecting, reading/writing, and waiting for bytes to become
37 /// available from a two way communication connection.
38 ///
39 /// This class is designed to only do very simple communication functions.
40 /// Instances can be instantiated and given to a Communication class to
41 /// perform communications where clients can listen for broadcasts, and
42 /// perform other higher level communications.
43 class Connection {
44 public:
45  /// Default constructor
46  Connection() = default;
47 
48  /// Virtual destructor since this class gets subclassed and handed to a
49  /// Communication object.
50  virtual ~Connection();
51 
52  /// Connect using the connect string \a url.
53  ///
54  /// \param[in] url
55  /// A string that contains all information needed by the
56  /// subclass to connect to another client.
57  ///
58  /// \param[out] error_ptr
59  /// A pointer to an error object that should be given an
60  /// appropriate error value if this method returns false. This
61  /// value can be NULL if the error value should be ignored.
62  ///
63  /// \return
64  /// \b True if the connect succeeded, \b false otherwise. The
65  /// internal error object should be filled in with an
66  /// appropriate value based on the result of this function.
67  ///
68  /// \see Status& Communication::GetError ();
69  virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
70  Status *error_ptr) = 0;
71 
72  /// Disconnect the communications connection if one is currently connected.
73  ///
74  /// \param[out] error_ptr
75  /// A pointer to an error object that should be given an
76  /// appropriate error value if this method returns false. This
77  /// value can be NULL if the error value should be ignored.
78  ///
79  /// \return
80  /// \b True if the disconnect succeeded, \b false otherwise. The
81  /// internal error object should be filled in with an
82  /// appropriate value based on the result of this function.
83  ///
84  /// \see Status& Communication::GetError ();
85  virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
86 
87  /// Check if the connection is valid.
88  ///
89  /// \return
90  /// \b True if this object is currently connected, \b false
91  /// otherwise.
92  virtual bool IsConnected() const = 0;
93 
94  /// The read function that attempts to read from the connection.
95  ///
96  /// \param[in] dst
97  /// A destination buffer that must be at least \a dst_len bytes
98  /// long.
99  ///
100  /// \param[in] dst_len
101  /// The number of bytes to attempt to read, and also the max
102  /// number of bytes that can be placed into \a dst.
103  ///
104  /// \param[in] timeout
105  /// The number of microseconds to wait for the data.
106  ///
107  /// \param[out] status
108  /// On return, indicates whether the call was successful or terminated
109  /// due to some error condition.
110  ///
111  /// \param[out] error_ptr
112  /// A pointer to an error object that should be given an
113  /// appropriate error value if this method returns zero. This
114  /// value can be NULL if the error value should be ignored.
115  ///
116  /// \return
117  /// The number of bytes actually read.
118  ///
119  /// \see size_t Communication::Read (void *, size_t, uint32_t);
120  virtual size_t Read(void *dst, size_t dst_len,
121  const Timeout<std::micro> &timeout,
122  lldb::ConnectionStatus &status, Status *error_ptr) = 0;
123 
124  /// The actual write function that attempts to write to the communications
125  /// protocol.
126  ///
127  /// Subclasses must override this function.
128  ///
129  /// \param[in] dst
130  /// A desination buffer that must be at least \a dst_len bytes
131  /// long.
132  ///
133  /// \param[in] dst_len
134  /// The number of bytes to attempt to write, and also the
135  /// number of bytes are currently available in \a dst.
136  ///
137  /// \param[out] error_ptr
138  /// A pointer to an error object that should be given an
139  /// appropriate error value if this method returns zero. This
140  /// value can be NULL if the error value should be ignored.
141  ///
142  /// \return
143  /// The number of bytes actually Written.
144  virtual size_t Write(const void *dst, size_t dst_len,
145  lldb::ConnectionStatus &status, Status *error_ptr) = 0;
146 
147  /// Returns a URI that describes this connection object
148  ///
149  /// Subclasses may override this function.
150  ///
151  /// \return
152  /// Returns URI or an empty string if disconnecteds
153  virtual std::string GetURI() = 0;
154 
155  /// Interrupts an ongoing Read() operation.
156  ///
157  /// If there is an ongoing read operation in another thread, this operation
158  /// return with status == eConnectionStatusInterrupted. Note that if there
159  /// data waiting to be read and an interrupt request is issued, the Read()
160  /// function will return the data immediately without processing the
161  /// interrupt request (which will remain queued for the next Read()
162  /// operation).
163  ///
164  /// \return
165  /// Returns true is the interrupt request was successful.
166  virtual bool InterruptRead() = 0;
167 
168  /// Returns the underlying IOObject used by the Connection.
169  ///
170  /// The IOObject can be used to wait for data to become available on the
171  /// connection. If the Connection does not use IOObjects (and hence does not
172  /// support waiting) this function should return a null pointer.
173  ///
174  /// \return
175  /// The underlying IOObject used for reading.
176  virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); }
177 
178 private:
179  // For Connection only
180  DISALLOW_COPY_AND_ASSIGN(Connection);
181 };
182 
183 } // namespace lldb_private
184 
185 #endif // liblldb_Connection_h_
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
virtual bool InterruptRead()=0
Interrupts an ongoing Read() operation.
Connection()=default
Default constructor.
virtual std::string GetURI()=0
Returns a URI that describes this connection object.
virtual bool IsConnected() const =0
Check if the connection is valid.
A communication connection class.
Definition: Connection.h:43
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.
virtual lldb::IOObjectSP GetReadObject()
Returns the underlying IOObject used by the Connection.
Definition: Connection.h:176
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.
virtual lldb::ConnectionStatus Connect(llvm::StringRef url, Status *error_ptr)=0
Connect using the connect string url.
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr)=0
Disconnect the communications connection if one is currently connected.
virtual ~Connection()
Virtual destructor since this class gets subclassed and handed to a Communication object...
An error handling class.
Definition: Status.h:44