|
|
//===-- Connection.h --------------------------------------------*- C++ -*-===//
//
// The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
#ifndef liblldb_Connection_h_
#define liblldb_Connection_h_
#include "lldb/lldb-defines.h" // for DISALLOW_COPY_AND_ASSIGN
#include "lldb/lldb-enumerations.h" // for ConnectionStatus
#include "lldb/lldb-forward.h" // for IOObjectSP
#include "llvm/ADT/StringRef.h" // for StringRef
#include <ratio> // for micro
#include <string>
#include <stddef.h> // for size_t
namespace lldb_private {
class Status;
}
namespace lldb_private {
template <typename Ratio> class Timeout;
}
namespace lldb_private {
//----------------------------------------------------------------------
/// @class Connection Connection.h "lldb/Utility/Connection.h"
/// @brief 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 desination 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
//------------------------------------------------------------------
DISALLOW_COPY_AND_ASSIGN(Connection);
};
} // namespace lldb_private
#endif // liblldb_Connection_h_
|
