An abstract communications class. More...

#include "lldb/Core/Communication.h"

Inheritance diagram for lldb_private::Communication:

[legend]

Collaboration diagram for lldb_private::Communication:

Public Types
typedef void(*	ReadThreadBytesReceived) (void baton, const void src, size_t src_len)

Public Member Functions
	FLAGS_ANONYMOUS_ENUM ()

	Communication (const char *broadcaster_name)
	Construct the Communication object with the specified name for the Broadcaster that this object inherits from. More...

	~Communication () override
	Destructor. More...

void	Clear ()

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

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

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

bool	HasConnection () const

lldb_private::Connection *	GetConnection ()

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. More...

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. More...

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

virtual bool	StartReadThread (Status *error_ptr=nullptr)
	Starts a read thread whose sole purpose it to read bytes from the current connection. More...

virtual bool	StopReadThread (Status *error_ptr=nullptr)
	Stops the read thread by cancelling it. More...

virtual bool	JoinReadThread (Status *error_ptr=nullptr)

bool	ReadThreadIsRunning ()
	Checks if there is a currently running read thread. More...

void	SetReadThreadBytesReceivedCallback (ReadThreadBytesReceived callback, void *callback_baton)

void	SynchronizeWithReadThread ()
	Wait for the read thread to process all outstanding data. More...

bool	GetCloseOnEOF () const

void	SetCloseOnEOF (bool b)

ConstString &	GetBroadcasterClass () const override
	This needs to be filled in if you are going to register the broadcaster with the broadcaster manager and do broadcaster class matching. More...

Public Member Functions inherited from lldb_private::Broadcaster
	Broadcaster (lldb::BroadcasterManagerSP manager_sp, const char *name)
	Construct with a broadcaster with a name. More...

virtual	~Broadcaster ()
	Destructor. More...

void	CheckInWithManager ()

void	BroadcastEvent (lldb::EventSP &event_sp)
	Broadcast an event which has no associated data. More...

void	BroadcastEventIfUnique (lldb::EventSP &event_sp)

void	BroadcastEvent (uint32_t event_type, const lldb::EventDataSP &event_data_sp)

void	BroadcastEvent (uint32_t event_type, EventData *event_data=nullptr)

void	BroadcastEventIfUnique (uint32_t event_type, EventData *event_data=nullptr)

void	Clear ()

virtual void	AddInitialEventsToListener (const lldb::ListenerSP &listener_sp, uint32_t requested_events)

uint32_t	AddListener (const lldb::ListenerSP &listener_sp, uint32_t event_mask)
	Listen for any events specified by event_mask. More...

ConstString	GetBroadcasterName ()
	Get the NULL terminated C string name of this Broadcaster object. More...

bool	GetEventNames (Stream &s, const uint32_t event_mask, bool prefix_with_broadcaster_name) const
	Get the event name(s) for one or more event bits. More...

void	SetEventName (uint32_t event_mask, const char *name)
	Set the name for an event bit. More...

const char *	GetEventName (uint32_t event_mask) const

bool	EventTypeHasListeners (uint32_t event_type)

bool	RemoveListener (const lldb::ListenerSP &listener_sp, uint32_t event_mask=UINT32_MAX)
	Removes a Listener from this broadcasters list and frees the event bits specified by event_mask that were previously acquired by listener (assuming listener was listening to this object) for other listener objects to use. More...

bool	HijackBroadcaster (const lldb::ListenerSP &listener_sp, uint32_t event_mask=UINT32_MAX)
	Provides a simple mechanism to temporarily redirect events from broadcaster. More...

bool	IsHijackedForEvent (uint32_t event_mask)

void	RestoreBroadcaster ()
	Restore the state of the Broadcaster from a previous hijack attempt. More...

lldb::BroadcasterManagerSP	GetManager ()

Static Public Member Functions
static lldb::thread_result_t	ReadThread (lldb::thread_arg_t comm_ptr)
	The static read thread function. More...

static const char *	ConnectionStatusAsCString (lldb::ConnectionStatus status)

static ConstString &	GetStaticBroadcasterClass ()

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

virtual void	AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast, lldb::ConnectionStatus status)
	Append new bytes that get read from the read thread into the internal object byte cache. More...

size_t	GetCachedBytes (void *dst, size_t dst_len)
	Get any available bytes from our data cache. More...

Protected Member Functions inherited from lldb_private::Broadcaster
BroadcasterImplSP	GetBroadcasterImpl ()

const char *	GetHijackingListenerName ()

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

HostThread	m_read_thread
	The read thread handle in case we need to cancel the thread. More...

std::atomic< bool >	m_read_thread_enabled

std::atomic< bool >	m_read_thread_did_exit

std::string	m_bytes
	A buffer to cache bytes read in the ReadThread function. More...

std::recursive_mutex	m_bytes_mutex
	A mutex to protect multi-threaded access to the cached bytes. More...

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

std::mutex	m_synchronize_mutex

ReadThreadBytesReceived	m_callback

void *	m_callback_baton

bool	m_close_on_eof

Private Member Functions
	Communication (const Communication &)=delete

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

Additional Inherited Members
Protected Types inherited from lldb_private::Broadcaster
typedef std::shared_ptr< BroadcasterImpl >	BroadcasterImplSP

typedef std::weak_ptr< BroadcasterImpl >	BroadcasterImplWP

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. It also allows this class to be subclassed by any interfaces that don't want to give bytes but want to validate and give out packets. This can be done by overriding:

AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast);

Communication inherits from Broadcaster which means it can be used in conjunction with Listener to wait for multiple broadcaster objects and multiple events from each of those objects. Communication defines a set of pre-defined event bits (see enumerations definitions that start with "eBroadcastBit" below).

There are two modes in which communications can occur:

single-threaded
multi-threaded

In single-threaded mode, all reads and writes happen synchronously on the calling thread.

In multi-threaded mode, a read thread is spawned that continually reads data and caches any received bytes. To start the read thread clients call:

bool Communication::StartReadThread (Status *);

If true is returned a read thread has been spawned that will continually execute a call to the pure virtual DoRead function:

size_t Communication::ReadFromConnection (void *, size_t, uint32_t);

When bytes are received the data gets cached in m_bytes and this class will broadcast a eBroadcastBitReadThreadGotBytes event. Clients that want packet based communication should override AppendBytesToCache. The subclasses can choose to call the built in AppendBytesToCache with the broadcast parameter set to false. This will cause the eBroadcastBitReadThreadGotBytes event not get broadcast, and then the subclass can post a eBroadcastBitPacketAvailable event when a full packet of data has been received.

If the connection is disconnected a eBroadcastBitDisconnected event gets broadcast. If the read thread exits a eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also post a eBroadcastBitReadThreadShouldExit event to this object which will cause the read thread to exit.

Definition at line 84 of file Communication.h.

Member Typedef Documentation

◆ ReadThreadBytesReceived

typedef void(* lldb_private::Communication::ReadThreadBytesReceived) (void *baton, const void *src, size_t src_len)

Definition at line 106 of file Communication.h.

Constructor & Destructor Documentation

◆ Communication() [1/2]

Communication::Communication ( const char * broadcaster_name )

Construct the Communication object with the specified name for the Broadcaster that this object inherits from.

Parameters

[in] broadcaster_name The name of the broadcaster object. This name should be as complete as possible to uniquely identify this object. The broadcaster name can be updated after the connect function is called.

Definition at line 42 of file Communication.cpp.

References lldb_private::Broadcaster::CheckInWithManager(), lldb_private::GetLogIfAnyCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LIBLLDB_LOG_OBJECT, LLDB_LOG, and lldb_private::Broadcaster::SetEventName().

◆ ~Communication()

Communication::~Communication ( )

override

Destructor.

The destructor is virtual since this class gets subclassed.

Definition at line 64 of file Communication.cpp.

References Clear(), lldb_private::Broadcaster::GetBroadcasterName(), lldb_private::GetLogIfAnyCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LIBLLDB_LOG_OBJECT, and LLDB_LOG.

◆ Communication() [2/2]

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

privatedelete

Member Function Documentation

◆ AppendBytesToCache()

void Communication::AppendBytesToCache	(	const uint8_t *	src,
		size_t	src_len,
		bool	broadcast,
		lldb::ConnectionStatus	status
	)

protectedvirtual

Append new bytes that get read from the read thread into the internal object byte cache.

This will cause a eBroadcastBitReadThreadGotBytes event to be broadcast if broadcast is true.

Subclasses can override this function in order to inspect the received data and check if a packet is available.

Subclasses can also still call this function from the overridden method to allow the caching to correctly happen and suppress the broadcasting of the eBroadcastBitReadThreadGotBytes event by setting broadcast to false.

Parameters

[in]	src	A source buffer that must be at least src_len bytes long.
[in]	src_len	The number of bytes to append to the cache.

Reimplemented in lldb_private::process_gdb_remote::GDBRemoteCommunication.

Definition at line 271 of file Communication.cpp.

References lldb_private::Broadcaster::BroadcastEventIfUnique(), lldb::eConnectionStatusEndOfFile, lldb_private::GetLogIfAllCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_bytes, m_bytes_mutex, m_callback, and m_callback_baton.

Referenced by ReadThread().

◆ Clear()

void Communication::Clear ( )

Definition at line 72 of file Communication.cpp.

References Disconnect(), SetReadThreadBytesReceivedCallback(), and StopReadThread().

Referenced by Connect(), 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 78 of file Communication.cpp.

References Clear(), lldb::eConnectionStatusNoConnection, lldb_private::GetLogIfAllCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_connection_sp, and lldb_private::Status::SetErrorString().

Referenced by lldb::SBCommunication::Connect(), and lldb_private::platform_gdb_server::PlatformRemoteGDBServer::ConnectRemote().

◆ ConnectionStatusAsCString()

const char * Communication::ConnectionStatusAsCString ( lldb::ConnectionStatus status )

static

Definition at line 421 of file Communication.cpp.

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

Referenced by GetConnection(), ReadThread(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::WaitForPacketNoLock().

◆ Disconnect()

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

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 ();

Definition at line 92 of file Communication.cpp.

References lldb::eConnectionStatusNoConnection, lldb_private::GetLogIfAllCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_connection_sp, m_read_thread_did_exit, and m_read_thread_enabled.

Referenced by lldb::SBCommunication::AdoptFileDesriptor(), lldb_private::process_gdb_remote::GDBRemoteCommunicationReplayServer::AsyncThread(), Clear(), lldb_private::platform_gdb_server::PlatformRemoteGDBServer::ConnectRemote(), lldb_private::Process::Destroy(), lldb::SBCommunication::Disconnect(), lldb_private::platform_gdb_server::PlatformRemoteGDBServer::DisconnectRemote(), Read(), ReadThread(), SetConnection(), lldb_private::Process::ShouldBroadcastEvent(), lldb_private::process_gdb_remote::GDBRemoteCommunicationReplayServer::StopAsyncThread(), lldb_private::process_gdb_remote::GDBRemoteCommunication::WaitForPacketNoLock(), CommunicationKDP::WaitForPacketWithTimeoutMicroSecondsNoLock(), CommunicationKDP::~CommunicationKDP(), lldb_private::process_gdb_remote::GDBRemoteCommunication::~GDBRemoteCommunication(), lldb_private::process_gdb_remote::GDBRemoteCommunicationClient::~GDBRemoteCommunicationClient(), and lldb_private::ScriptInterpreterIORedirect::~ScriptInterpreterIORedirect().

◆ FLAGS_ANONYMOUS_ENUM()

lldb_private::Communication::FLAGS_ANONYMOUS_ENUM ( )

inline

< Sent when the communications connection is lost.

< Sent by the read thread when bytes become available.

< Sent by the read thread when it exits to inform clients.

< Sent by clients that need to cancel the read thread.

< Sent when data received makes a complete packet.

< Sent by the read thread to indicate all pending input has been processed.

< Subclasses can used bits 31:16 for any needed events.

Definition at line 86 of file Communication.h.

◆ GetBroadcasterClass()

ConstString& lldb_private::Communication::GetBroadcasterClass ( ) const

inlineoverridevirtual

This needs to be filled in if you are going to register the broadcaster with the broadcaster manager and do broadcaster class matching.

FIXME: Probably should make a ManagedBroadcaster subclass with all the bits needed to work with the BroadcasterManager, so that it is clearer how to add one.

Reimplemented from lldb_private::Broadcaster.

Definition at line 296 of file Communication.h.

References GetStaticBroadcasterClass().

◆ GetCachedBytes()

size_t Communication::GetCachedBytes	(	void *	dst,
		size_t	dst_len
	)

protected

Get any available bytes from our data cache.

If this call empties the data cache, the eBroadcastBitReadThreadGotBytes event will be reset to signify no more bytes are 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 from the cache, and also the max number of bytes that can be placed into dst.

Returns: The number of bytes extracted from the data cache.

Definition at line 253 of file Communication.cpp.

References m_bytes, and m_bytes_mutex.

Referenced by Read().

◆ GetCloseOnEOF()

bool lldb_private::Communication::GetCloseOnEOF ( ) const

inline

Definition at line 290 of file Communication.h.

References m_close_on_eof.

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

◆ GetConnection()

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

inline

Definition at line 162 of file Communication.h.

References ConnectionStatusAsCString(), JoinReadThread(), m_connection_sp, Read(), ReadThread(), ReadThreadIsRunning(), SetConnection(), SetReadThreadBytesReceivedCallback(), StartReadThread(), StopReadThread(), SynchronizeWithReadThread(), and Write().

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

◆ GetStaticBroadcasterClass()

ConstString & Communication::GetStaticBroadcasterClass ( )

static

Definition at line 37 of file Communication.cpp.

Referenced by GetBroadcasterClass(), and SetCloseOnEOF().

◆ HasConnection()

bool Communication::HasConnection ( ) const

Definition at line 121 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 116 of file Communication.cpp.

References m_connection_sp.

◆ JoinReadThread()

bool Communication::JoinReadThread ( Status * error_ptr = nullptr )

virtual

Definition at line 245 of file Communication.cpp.

References error(), lldb_private::HostThread::IsJoinable(), lldb_private::HostThread::Join(), m_read_thread, and lldb_private::Status::Success().

Referenced by GetConnection(), and lldb_private::ScriptInterpreterIORedirect::~ScriptInterpreterIORedirect().

◆ 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
	)

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.

If a read thread has been started, this function will check for any cached bytes that have already been read and return any currently available bytes. If no bytes are cached, it will wait for the bytes to become available by listening for the eBroadcastBitReadThreadGotBytes event. If this function consumes all of the bytes in the cache, it will reset the eBroadcastBitReadThreadGotBytes event bit.

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 llvm::None for no timeout.

Returns: The number of bytes actually read.

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

Definition at line 125 of file Communication.cpp.

References Disconnect(), lldb::eConnectionStatusNoConnection, lldb::eConnectionStatusSuccess, GetCachedBytes(), GetCloseOnEOF(), lldb_private::GetLogIfAllCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_connection_sp, m_read_thread_enabled, lldb_private::Listener::MakeListener(), ReadFromConnection(), and lldb_private::Status::SetErrorString().

Referenced by GetConnection(), lldb::SBCommunication::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 292 of file Communication.cpp.

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

Referenced by Read(), and ReadThread().

◆ ReadThread()

lldb::thread_result_t Communication::ReadThread ( lldb::thread_arg_t comm_ptr )

static

The static read thread function.

This function will call the "DoRead" function continuously and wait for data to become available. When data is received it will append the available data to the internal cache and broadcast a eBroadcastBitReadThreadGotBytes event.

Parameters

[in] comm_ptr A pointer to an instance of this class.

Returns: NULL.

See also: void Communication::ReadThreadGotBytes (const uint8_t *, size_t);

Definition at line 308 of file Communication.cpp.

References AppendBytesToCache(), lldb_private::Broadcaster::BroadcastEvent(), ConnectionStatusAsCString(), Disconnect(), lldb::eConnectionStatusEndOfFile, lldb::eConnectionStatusError, lldb::eConnectionStatusInterrupted, lldb::eConnectionStatusLostConnection, lldb::eConnectionStatusNoConnection, lldb::eConnectionStatusSuccess, lldb::eConnectionStatusTimedOut, lldb::eErrorTypePOSIX, error(), lldb_private::Status::Fail(), GetCloseOnEOF(), lldb_private::Status::GetError(), lldb_private::GetLogIfAllCategoriesSet(), lldb_private::Status::GetType(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, LLDB_LOGF, m_read_thread_did_exit, m_read_thread_enabled, m_synchronize_mutex, and ReadFromConnection().

Referenced by GetConnection(), and StartReadThread().

◆ ReadThreadIsRunning()

bool Communication::ReadThreadIsRunning ( )

Checks if there is a currently running read thread.

Returns: True if the read thread is running, false otherwise.

Definition at line 306 of file Communication.cpp.

References m_read_thread_enabled.

Referenced by GetConnection(), and lldb::SBCommunication::ReadThreadIsRunning().

◆ SetCloseOnEOF()

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

inline

Definition at line 292 of file Communication.h.

References GetStaticBroadcasterClass(), and 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 )

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

Definition at line 414 of file Communication.cpp.

References Disconnect(), m_connection_sp, and StopReadThread().

Referenced by lldb::SBCommunication::AdoptFileDesriptor(), lldb::SBCommunication::Connect(), lldb_private::process_gdb_remote::GDBRemoteCommunication::ConnectLocally(), lldb_private::platform_gdb_server::PlatformRemoteGDBServer::ConnectRemote(), GetConnection(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::InitializeConnection(), lldb_private::process_gdb_remote::GDBRemoteCommunication::ListenThread(), lldb_private::ScriptInterpreterIORedirect::ScriptInterpreterIORedirect(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::SetSTDIOFileDescriptor(), lldb_private::Process::SetSTDIOFileDescriptor(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::StartListenThread().

◆ SetReadThreadBytesReceivedCallback()

void Communication::SetReadThreadBytesReceivedCallback	(	ReadThreadBytesReceived	callback,
		void *	callback_baton
	)

Definition at line 387 of file Communication.cpp.

References m_callback, and m_callback_baton.

Referenced by Clear(), GetConnection(), lldb_private::ScriptInterpreterIORedirect::ScriptInterpreterIORedirect(), lldb::SBCommunication::SetReadThreadBytesReceivedCallback(), and lldb_private::Process::SetSTDIOFileDescriptor().

◆ StartReadThread()

bool Communication::StartReadThread ( Status * error_ptr = nullptr )

virtual

Starts a read thread whose sole purpose it to read bytes from the current connection.

This function will call connection's read function:

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

When bytes are read and cached, this function will call:

Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);

Subclasses should override this function if they wish to override the default action of caching the bytes and broadcasting a eBroadcastBitReadThreadGotBytes event.

Returns: True if the read thread was successfully started, false otherwise.

See also: size_t Connection::Read (void *, size_t);; void Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool broadcast);

Definition at line 192 of file Communication.cpp.

References lldb_private::Status::Clear(), lldb_private::Broadcaster::GetBroadcasterName(), lldb_private::GetLogIfAllCategoriesSet(), lldb_private::HostThread::IsJoinable(), lldb_private::ThreadLauncher::LaunchThread(), LIBLLDB_LOG_COMMUNICATION, LIBLLDB_LOG_HOST, LLDB_LOG, m_read_thread, m_read_thread_did_exit, m_read_thread_enabled, ReadThread(), lldb_private::Status, and lldb_private::breakpad::toString().

Referenced by GetConnection(), lldb::SBCommunication::ReadThreadStart(), lldb_private::ScriptInterpreterIORedirect::ScriptInterpreterIORedirect(), and lldb_private::Process::SetSTDIOFileDescriptor().

◆ StopReadThread()

bool Communication::StopReadThread ( Status * error_ptr = nullptr )

virtual

Stops the read thread by cancelling it.

Returns: True if the read thread was successfully canceled, false otherwise.

Definition at line 228 of file Communication.cpp.

References lldb_private::Broadcaster::BroadcastEvent(), error(), lldb_private::GetLogIfAllCategoriesSet(), lldb_private::HostThread::IsJoinable(), lldb_private::HostThread::Join(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_read_thread, m_read_thread_enabled, and lldb_private::Status::Success().

Referenced by Clear(), lldb_private::Process::Destroy(), GetConnection(), lldb::SBCommunication::ReadThreadStop(), SetConnection(), lldb_private::Process::ShouldBroadcastEvent(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::~GDBRemoteCommunication().

◆ SynchronizeWithReadThread()

void Communication::SynchronizeWithReadThread ( )

Wait for the read thread to process all outstanding data.

After this function returns, the read thread has processed all data that has been waiting in the Connection queue.

Definition at line 393 of file Communication.cpp.

References m_connection_sp, m_read_thread_did_exit, m_read_thread_enabled, m_synchronize_mutex, and lldb_private::Listener::MakeListener().

Referenced by GetConnection(), and lldb_private::Process::ShouldBroadcastEvent().

◆ 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 173 of file Communication.cpp.

References lldb::eConnectionStatusNoConnection, lldb_private::GetLogIfAllCategoriesSet(), LIBLLDB_LOG_COMMUNICATION, LLDB_LOG, m_connection_sp, m_write_mutex, and lldb_private::Status::SetErrorString().

Referenced by GetConnection(), lldb_private::process_gdb_remote::GDBRemoteCommunicationServerLLGS::Handle_I(), lldb_private::process_gdb_remote::GDBRemoteCommunication::SendAck(), lldb_private::process_gdb_remote::GDBRemoteCommunication::SendNack(), lldb_private::process_gdb_remote::GDBRemoteCommunication::SendRawPacketNoLock(), CommunicationKDP::SendRequestPacketNoLock(), lldb_private::process_gdb_remote::GDBRemoteClientBase::Lock::SyncWithContinueThread(), and lldb::SBCommunication::Write().

Member Data Documentation

◆ m_bytes

std::string lldb_private::Communication::m_bytes

protected

A buffer to cache bytes read in the ReadThread function.

Definition at line 308 of file Communication.h.

Referenced by AppendBytesToCache(), CommunicationKDP::CheckForPacket(), lldb_private::process_gdb_remote::GDBRemoteCommunication::CheckForPacket(), lldb_private::process_gdb_remote::GDBRemoteCommunication::DecompressPacket(), and GetCachedBytes().

◆ m_bytes_mutex

std::recursive_mutex lldb_private::Communication::m_bytes_mutex

protected

A mutex to protect multi-threaded access to the cached bytes.

Definition at line 309 of file Communication.h.

Referenced by AppendBytesToCache(), CommunicationKDP::CheckForPacket(), lldb_private::process_gdb_remote::GDBRemoteCommunication::CheckForPacket(), and GetCachedBytes().

◆ m_callback

ReadThreadBytesReceived lldb_private::Communication::m_callback

protected

Definition at line 314 of file Communication.h.

Referenced by AppendBytesToCache(), and SetReadThreadBytesReceivedCallback().

◆ m_callback_baton

void* lldb_private::Communication::m_callback_baton

protected

Definition at line 315 of file Communication.h.

Referenced by AppendBytesToCache(), and SetReadThreadBytesReceivedCallback().

◆ m_close_on_eof

bool lldb_private::Communication::m_close_on_eof

protected

Definition at line 316 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 301 of file Communication.h.

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

◆ m_read_thread

HostThread lldb_private::Communication::m_read_thread

protected

The read thread handle in case we need to cancel the thread.

Definition at line 303 of file Communication.h.

Referenced by JoinReadThread(), StartReadThread(), and StopReadThread().

◆ m_read_thread_did_exit

std::atomic<bool> lldb_private::Communication::m_read_thread_did_exit

protected

Definition at line 306 of file Communication.h.

Referenced by Disconnect(), ReadThread(), StartReadThread(), and SynchronizeWithReadThread().

◆ m_read_thread_enabled

std::atomic<bool> lldb_private::Communication::m_read_thread_enabled

protected

Definition at line 305 of file Communication.h.

Referenced by Disconnect(), Read(), lldb_private::process_gdb_remote::GDBRemoteCommunication::ReadPacket(), ReadThread(), ReadThreadIsRunning(), StartReadThread(), StopReadThread(), SynchronizeWithReadThread(), and lldb_private::process_gdb_remote::GDBRemoteCommunication::~GDBRemoteCommunication().

◆ m_synchronize_mutex

std::mutex lldb_private::Communication::m_synchronize_mutex

protected

Definition at line 313 of file Communication.h.

Referenced by ReadThread(), and SynchronizeWithReadThread().

◆ 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 312 of file Communication.h.

Referenced by Write().

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ReadThreadBytesReceived

Constructor & Destructor Documentation

◆ Communication() [1/2]

◆ ~Communication()

◆ Communication() [2/2]

Member Function Documentation

◆ AppendBytesToCache()

◆ Clear()

◆ Connect()

◆ ConnectionStatusAsCString()

◆ Disconnect()

◆ FLAGS_ANONYMOUS_ENUM()

◆ GetBroadcasterClass()

◆ GetCachedBytes()

◆ GetCloseOnEOF()

◆ GetConnection()

◆ GetStaticBroadcasterClass()

◆ HasConnection()

◆ IsConnected()

◆ JoinReadThread()

◆ operator=()

◆ Read()

◆ ReadFromConnection()

◆ ReadThread()

◆ ReadThreadIsRunning()

◆ SetCloseOnEOF()

◆ SetConnection()

◆ SetReadThreadBytesReceivedCallback()

◆ StartReadThread()

◆ StopReadThread()

◆ SynchronizeWithReadThread()

◆ Write()

Member Data Documentation

◆ m_bytes

◆ m_bytes_mutex

◆ m_callback

◆ m_callback_baton

◆ m_close_on_eof

◆ m_connection_sp

◆ m_read_thread

◆ m_read_thread_did_exit

◆ m_read_thread_enabled

◆ m_synchronize_mutex

◆ m_write_mutex