An abstract communications class. More...

#include "lldb/Core/Communication.h"

Inheritance diagram for lldb_private::Communication:

[legend]

Collaboration diagram for lldb_private::Communication:

[legend]

Public Member Functions
	Communication ()
	Construct the Communication object.

virtual	~Communication ()
	Destructor.

virtual void	Clear ()

lldb::ConnectionStatus	Connect (const char url, Status error_ptr)
	Connect using the current connection by passing url to its connect function.

virtual lldb::ConnectionStatus	Disconnect (Status *error_ptr=nullptr)
	Disconnect the communications connection if one is currently connected.

bool	IsConnected () const
	Check if the connection is valid.

bool	HasConnection () const

lldb_private::Connection *	GetConnection ()

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.

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.

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.

virtual void	SetConnection (std::unique_ptr< Connection > connection)
	Sets the connection that it to be used by this class.

bool	GetCloseOnEOF () const

void	SetCloseOnEOF (bool b)

Static Public Member Functions
static std::string	ConnectionStatusAsString (lldb::ConnectionStatus status)

Protected Member Functions
size_t	ReadFromConnection (void dst, size_t dst_len, const Timeout< std::micro > &timeout, lldb::ConnectionStatus &status, Status error_ptr)

Protected Attributes
lldb::ConnectionSP	m_connection_sp
	The connection that is current in use by this communications class.

std::mutex	m_write_mutex
	Don't let multiple threads write at the same time...

bool	m_close_on_eof

Private Member Functions
	Communication (const Communication &)=delete

const Communication &	operator= (const Communication &)=delete

Detailed Description

An abstract communications class.

Communication is an class that handles data communication between two data sources. It uses a Connection class to do the real communication. This approach has a couple of advantages: it allows a single instance of this class to be used even though its connection can change. Connections could negotiate for different connections based on abilities like starting with Bluetooth and negotiating up to WiFi if available.

When using this class, all reads and writes happen synchronously on the calling thread. There is also a ThreadedCommunication class that supports multi-threaded mode.

Definition at line 39 of file Communication.h.

Constructor & Destructor Documentation

◆ Communication() [1/2]

Communication::Communication ( )

Construct the Communication object.

Definition at line 29 of file Communication.cpp.

◆ ~Communication()

Communication::~Communication ( )

virtual

Destructor.

The destructor is virtual since this class gets subclassed.

Definition at line 33 of file Communication.cpp.

References Clear().

◆ Communication() [2/2]

lldb_private::Communication::Communication ( const Communication & )

privatedelete

Member Function Documentation

◆ Clear()

void Communication::Clear ( )

virtual

Reimplemented in lldb_private::ThreadedCommunication.

Definition at line 37 of file Communication.cpp.

References Disconnect().

Referenced by lldb_private::ThreadedCommunication::Clear(), ProcessKDP::DoDetach(), and ~Communication().

◆ Connect()

ConnectionStatus Communication::Connect	(	const char *	url,
		Status *	error_ptr
	)

Connect using the current connection by passing url to its connect function.

string.

Parameters

[in] url A string that contains all information needed by the subclass to connect to another client.

Returns: True if the connect succeeded, false otherwise. The internal error object should be filled in with an appropriate value based on the result of this function.

See also: Status& Communication::GetError ();; bool Connection::Connect (const char *url);

Definition at line 41 of file Communication.cpp.

Referenced by lldb::SBCommunication::Connect().

◆ ConnectionStatusAsString()

std::string Communication::ConnectionStatusAsString ( lldb::ConnectionStatus status )

static

Definition at line 147 of file Communication.cpp.

References lldb::eConnectionStatusEndOfFile, lldb::eConnectionStatusError, lldb::eConnectionStatusInterrupted, lldb::eConnectionStatusLostConnection, lldb::eConnectionStatusNoConnection, lldb::eConnectionStatusSuccess, and lldb::eConnectionStatusTimedOut.

Referenced by lldb_private::ThreadedCommunication::ReadThread(), lldb_private::process_gdb_remote::GDBRemoteCommunication::WaitForPacketNoLock(), and CommunicationKDP::WaitForPacketWithTimeoutMicroSecondsNoLock().

◆ Disconnect()

ConnectionStatus Communication::Disconnect ( Status * error_ptr = nullptr )

virtual

Disconnect the communications connection if one is currently connected.

Returns: True if the disconnect succeeded, false otherwise. The internal error object should be filled in with an appropriate value based on the result of this function.

See also: Status& Communication::GetError ();; bool Connection::Disconnect ();

Reimplemented in lldb_private::ThreadedCommunication.

Definition at line 55 of file Communication.cpp.

References lldb_private::Communication, lldb::eConnectionStatusNoConnection, lldb_private::GetLog(), LLDB_LOG, and m_connection_sp.

Referenced by Clear(), lldb_private::process_gdb_remote::ProcessGDBRemote::ConnectToDebugserver(), lldb_private::process_gdb_remote::ProcessGDBRemote::DidExit(), lldb_private::ThreadedCommunication::Disconnect(), ProcessKDP::DoConnectRemote(), ProcessKDP::DoDetach(), lldb_private::process_gdb_remote::ProcessGDBRemote::DoHalt(), lldb_private::process_gdb_remote::ProcessGDBRemote::KillDebugserverProcess(), SetConnection(), lldb_private::process_gdb_remote::ProcessGDBRemote::StopAsyncThread(), lldb_private::process_gdb_remote::GDBRemoteCommunication::WaitForPacketNoLock(), CommunicationKDP::WaitForPacketWithTimeoutMicroSecondsNoLock(), CommunicationKDP::~CommunicationKDP(), lldb_private::process_gdb_remote::GDBRemoteCommunication::~GDBRemoteCommunication(), and lldb_private::process_gdb_remote::GDBRemoteCommunicationClient::~GDBRemoteCommunicationClient().

◆ GetCloseOnEOF()

bool lldb_private::Communication::GetCloseOnEOF ( ) const

inline

Definition at line 163 of file Communication.h.

References m_close_on_eof.

Referenced by lldb::SBCommunication::GetCloseOnEOF(), lldb_private::ThreadedCommunication::Read(), and lldb_private::ThreadedCommunication::ReadThread().

◆ GetConnection()

lldb_private::Connection * lldb_private::Communication::GetConnection ( )

inline

Definition at line 87 of file Communication.h.

References m_connection_sp.

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunicationServerPlatform::LaunchGDBServer(), lldb_private::process_gdb_remote::GDBRemoteCommunication::ListenThread(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::MaybeCloseInferiorTerminalConnection(), and lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::StartSTDIOForwarding().

◆ HasConnection()

bool Communication::HasConnection ( ) const

Definition at line 82 of file Communication.cpp.

References m_connection_sp.

Referenced by lldb::SBCommunication::AdoptFileDesriptor(), and lldb::SBCommunication::Connect().

◆ IsConnected()

bool Communication::IsConnected ( ) const

Check if the connection is valid.

Returns: True if this object is currently connected, false otherwise.

Definition at line 77 of file Communication.cpp.

References m_connection_sp.

◆ operator=()

const Communication & lldb_private::Communication::operator= ( const Communication & )

privatedelete

◆ Read()

size_t Communication::Read	(	void *	dst,
		size_t	dst_len,
		const Timeout< std::micro > &	timeout,
		lldb::ConnectionStatus &	status,
		Status *	error_ptr
	)

virtual

Read bytes from the current connection.

If no read thread is running, this function call the connection's Connection::Read(...) function to get any available.

Parameters

[in]	dst	A destination buffer that must be at least dst_len bytes long.
[in]	dst_len	The number of bytes to attempt to read, and also the max number of bytes that can be placed into dst.
[in]	timeout	A timeout value or std::nullopt for no timeout.

Returns: The number of bytes actually read.

See also: size_t Connection::Read (void *, size_t);

Reimplemented in lldb_private::ThreadedCommunication.

Definition at line 86 of file Communication.cpp.

References lldb_private::Communication, lldb_private::GetLog(), LLDB_LOG, m_connection_sp, and ReadFromConnection().

Referenced by lldb_private::ThreadedCommunication::Read(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::SendProcessOutput(), lldb_private::process_gdb_remote::GDBRemoteCommunication::WaitForPacketNoLock(), and CommunicationKDP::WaitForPacketWithTimeoutMicroSecondsNoLock().

◆ ReadFromConnection()

size_t Communication::ReadFromConnection	(	void *	dst,
		size_t	dst_len,
		const Timeout< std::micro > &	timeout,
		lldb::ConnectionStatus &	status,
		Status *	error_ptr
	)

protected

Definition at line 127 of file Communication.cpp.

References lldb::eConnectionStatusNoConnection, m_connection_sp, and lldb_private::Status::SetErrorString().

Referenced by Read(), and lldb_private::ThreadedCommunication::ReadThread().

◆ SetCloseOnEOF()

void lldb_private::Communication::SetCloseOnEOF ( bool b )

inline

Definition at line 165 of file Communication.h.

References m_close_on_eof.

Referenced by lldb::SBCommunication::SetCloseOnEOF(), and lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::SetSTDIOFileDescriptor().

◆ SetConnection()

void Communication::SetConnection ( std::unique_ptr< Connection > connection )

virtual

Sets the connection that it to be used by this class.

By making a communication class that uses different connections it allows a single communication interface to negotiate and change its connection without any interruption to the client. It also allows the Communication class to be subclassed for packet based communication.

Parameters

[in] connection A connection that this class will own and destroy.

See also: class Connection

Reimplemented in lldb_private::ThreadedCommunication.

Definition at line 141 of file Communication.cpp.

References Disconnect(), and m_connection_sp.

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunication::ConnectLocally(), lldb_private::process_gdb_remote::ProcessGDBRemote::ConnectToDebugserver(), ProcessKDP::DoConnectRemote(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::InitializeConnection(), lldb_private::process_gdb_remote::ProcessGDBRemote::LaunchAndConnectToDebugserver(), lldb_private::process_gdb_remote::GDBRemoteCommunication::ListenThread(), lldb_private::ThreadedCommunication::SetConnection(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::SetSTDIOFileDescriptor(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::StartListenThread().

◆ Write()

size_t Communication::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.

Subclasses must override this function.

Parameters

[in]	src	A source buffer that must be at least src_len bytes long.
[in]	src_len	The number of bytes to attempt to write, and also the number of bytes are currently available in src.

Returns: The number of bytes actually Written.

Definition at line 98 of file Communication.cpp.

References lldb_private::Communication, lldb::eConnectionStatusNoConnection, lldb_private::GetLog(), LLDB_LOG, m_connection_sp, m_write_mutex, and lldb_private::Status::SetErrorString().

Referenced by CommunicationKDP::SendRequestPacketNoLock(), lldb::SBCommunication::Write(), and WriteAll().

◆ WriteAll()

size_t Communication::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.

Parameters

[in]	src	A source buffer that must be at least src_len bytes long.
[in]	src_len	The number of bytes to attempt to write, and also the number of bytes are currently available in src.

Returns: The number of bytes actually Written.

Definition at line 117 of file Communication.cpp.

References lldb::eConnectionStatusSuccess, and Write().

Referenced by lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::Handle_I(), lldb_private::process_gdb_remote::ProcessGDBRemote::PutSTDIN(), lldb_private::process_gdb_remote::GDBRemoteCommunication::SendAck(), lldb_private::process_gdb_remote::GDBRemoteCommunication::SendNack(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::SendRawPacketNoLock().

Member Data Documentation

◆ m_close_on_eof

bool lldb_private::Communication::m_close_on_eof

protected

Definition at line 172 of file Communication.h.

Referenced by GetCloseOnEOF(), and SetCloseOnEOF().

◆ m_connection_sp

lldb::ConnectionSP lldb_private::Communication::m_connection_sp

protected

The connection that is current in use by this communications class.

Definition at line 168 of file Communication.h.

Referenced by Disconnect(), GetConnection(), HasConnection(), IsConnected(), Read(), lldb_private::ThreadedCommunication::Read(), ReadFromConnection(), SetConnection(), lldb_private::ThreadedCommunication::SynchronizeWithReadThread(), and Write().

◆ m_write_mutex

std::mutex lldb_private::Communication::m_write_mutex

protected

Don't let multiple threads write at the same time...

Definition at line 171 of file Communication.h.

Referenced by Write().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Communication() [1/2]

◆ ~Communication()

◆ Communication() [2/2]

Member Function Documentation

◆ Clear()

◆ Connect()

◆ ConnectionStatusAsString()

◆ Disconnect()

◆ GetCloseOnEOF()

◆ GetConnection()

◆ HasConnection()

◆ IsConnected()

◆ operator=()

◆ Read()

◆ ReadFromConnection()

◆ SetCloseOnEOF()

◆ SetConnection()

◆ Write()

◆ WriteAll()

Member Data Documentation

◆ m_close_on_eof

◆ m_connection_sp

◆ m_write_mutex