You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
185 lines
6.4 KiB
185 lines
6.4 KiB
//===-- Connection.h --------------------------------------------*- C++ -*-===//
|
|
//
|
|
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
// See https://llvm.org/LICENSE.txt for license information.
|
|
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef LLDB_UTILITY_CONNECTION_H
|
|
#define LLDB_UTILITY_CONNECTION_H
|
|
|
|
#include "lldb/lldb-defines.h"
|
|
#include "lldb/lldb-enumerations.h"
|
|
#include "lldb/lldb-forward.h"
|
|
|
|
#include "llvm/ADT/StringRef.h"
|
|
|
|
#include <ratio>
|
|
#include <string>
|
|
|
|
#include <stddef.h>
|
|
|
|
namespace lldb_private {
|
|
class Status;
|
|
template <typename Ratio> class Timeout;
|
|
}
|
|
|
|
namespace lldb_private {
|
|
|
|
/// \class Connection Connection.h "lldb/Utility/Connection.h"
|
|
/// A communication connection class.
|
|
///
|
|
/// A class that implements that actual communication functions for
|
|
/// connecting/disconnecting, reading/writing, and waiting for bytes to become
|
|
/// available from a two way communication connection.
|
|
///
|
|
/// This class is designed to only do very simple communication functions.
|
|
/// Instances can be instantiated and given to a Communication class to
|
|
/// perform communications where clients can listen for broadcasts, and
|
|
/// perform other higher level communications.
|
|
class Connection {
|
|
public:
|
|
/// Default constructor
|
|
Connection() = default;
|
|
|
|
/// Virtual destructor since this class gets subclassed and handed to a
|
|
/// Communication object.
|
|
virtual ~Connection();
|
|
|
|
/// Connect using the connect string \a url.
|
|
///
|
|
/// \param[in] url
|
|
/// A string that contains all information needed by the
|
|
/// subclass to connect to another client.
|
|
///
|
|
/// \param[out] error_ptr
|
|
/// A pointer to an error object that should be given an
|
|
/// appropriate error value if this method returns false. This
|
|
/// value can be NULL if the error value should be ignored.
|
|
///
|
|
/// \return
|
|
/// \b True if the connect succeeded, \b false otherwise. The
|
|
/// internal error object should be filled in with an
|
|
/// appropriate value based on the result of this function.
|
|
///
|
|
/// \see Status& Communication::GetError ();
|
|
virtual lldb::ConnectionStatus Connect(llvm::StringRef url,
|
|
Status *error_ptr) = 0;
|
|
|
|
/// Disconnect the communications connection if one is currently connected.
|
|
///
|
|
/// \param[out] error_ptr
|
|
/// A pointer to an error object that should be given an
|
|
/// appropriate error value if this method returns false. This
|
|
/// value can be NULL if the error value should be ignored.
|
|
///
|
|
/// \return
|
|
/// \b True if the disconnect succeeded, \b false otherwise. The
|
|
/// internal error object should be filled in with an
|
|
/// appropriate value based on the result of this function.
|
|
///
|
|
/// \see Status& Communication::GetError ();
|
|
virtual lldb::ConnectionStatus Disconnect(Status *error_ptr) = 0;
|
|
|
|
/// Check if the connection is valid.
|
|
///
|
|
/// \return
|
|
/// \b True if this object is currently connected, \b false
|
|
/// otherwise.
|
|
virtual bool IsConnected() const = 0;
|
|
|
|
/// The read function that attempts to read from the connection.
|
|
///
|
|
/// \param[in] dst
|
|
/// A destination buffer that must be at least \a dst_len bytes
|
|
/// long.
|
|
///
|
|
/// \param[in] dst_len
|
|
/// The number of bytes to attempt to read, and also the max
|
|
/// number of bytes that can be placed into \a dst.
|
|
///
|
|
/// \param[in] timeout
|
|
/// The number of microseconds to wait for the data.
|
|
///
|
|
/// \param[out] status
|
|
/// On return, indicates whether the call was successful or terminated
|
|
/// due to some error condition.
|
|
///
|
|
/// \param[out] error_ptr
|
|
/// A pointer to an error object that should be given an
|
|
/// appropriate error value if this method returns zero. This
|
|
/// value can be NULL if the error value should be ignored.
|
|
///
|
|
/// \return
|
|
/// The number of bytes actually read.
|
|
///
|
|
/// \see size_t Communication::Read (void *, size_t, uint32_t);
|
|
virtual size_t Read(void *dst, size_t dst_len,
|
|
const Timeout<std::micro> &timeout,
|
|
lldb::ConnectionStatus &status, Status *error_ptr) = 0;
|
|
|
|
/// The actual write function that attempts to write to the communications
|
|
/// protocol.
|
|
///
|
|
/// Subclasses must override this function.
|
|
///
|
|
/// \param[in] dst
|
|
/// A destination buffer that must be at least \a dst_len bytes
|
|
/// long.
|
|
///
|
|
/// \param[in] dst_len
|
|
/// The number of bytes to attempt to write, and also the
|
|
/// number of bytes are currently available in \a dst.
|
|
///
|
|
/// \param[out] error_ptr
|
|
/// A pointer to an error object that should be given an
|
|
/// appropriate error value if this method returns zero. This
|
|
/// value can be NULL if the error value should be ignored.
|
|
///
|
|
/// \return
|
|
/// The number of bytes actually Written.
|
|
virtual size_t Write(const void *dst, size_t dst_len,
|
|
lldb::ConnectionStatus &status, Status *error_ptr) = 0;
|
|
|
|
/// Returns a URI that describes this connection object
|
|
///
|
|
/// Subclasses may override this function.
|
|
///
|
|
/// \return
|
|
/// Returns URI or an empty string if disconnecteds
|
|
virtual std::string GetURI() = 0;
|
|
|
|
/// Interrupts an ongoing Read() operation.
|
|
///
|
|
/// If there is an ongoing read operation in another thread, this operation
|
|
/// return with status == eConnectionStatusInterrupted. Note that if there
|
|
/// data waiting to be read and an interrupt request is issued, the Read()
|
|
/// function will return the data immediately without processing the
|
|
/// interrupt request (which will remain queued for the next Read()
|
|
/// operation).
|
|
///
|
|
/// \return
|
|
/// Returns true is the interrupt request was successful.
|
|
virtual bool InterruptRead() = 0;
|
|
|
|
/// Returns the underlying IOObject used by the Connection.
|
|
///
|
|
/// The IOObject can be used to wait for data to become available on the
|
|
/// connection. If the Connection does not use IOObjects (and hence does not
|
|
/// support waiting) this function should return a null pointer.
|
|
///
|
|
/// \return
|
|
/// The underlying IOObject used for reading.
|
|
virtual lldb::IOObjectSP GetReadObject() { return lldb::IOObjectSP(); };
|
|
|
|
private:
|
|
// For Connection only
|
|
Connection(const Connection &) = delete;
|
|
const Connection &operator=(const Connection &) = delete;
|
|
};
|
|
|
|
} // namespace lldb_private
|
|
|
|
#endif // LLDB_UTILITY_CONNECTION_H
|