#include <Telemetry.h>

Classes
struct	TelemetryEventData

Public Types
enum	ConnectionMode { None , Server , Client }
	Defines how the plTelemetry system was configured. More...

enum	TransmitMode { Reliable , Unreliable }
	Describes how to send messages. More...

Static Public Member Functions
Connection Configuration
static plResult	ConnectToServer (plStringView sConnectTo={})
	Starts a connection as a 'Client' to one server.

static void	CreateServer ()
	Opens a connection as a server.

static void	CloseConnection ()
	Closes any connection previously opened using ConnectToServer() or CreateServer().

Sending Data
static void	Broadcast (TransmitMode tm, plUInt32 uiSystemID, plUInt32 uiMsgID, const void *pData, plUInt32 uiDataBytes)

static void	Broadcast (TransmitMode tm, plUInt32 uiSystemID, plUInt32 uiMsgID, plStreamReader &inout_stream, plInt32 iDataBytes=-1)

static void	Broadcast (TransmitMode tm, plTelemetryMessage &ref_msg)

static void	SendToServer (plUInt32 uiSystemID, plUInt32 uiMsgID, const void *pData=nullptr, plUInt32 uiDataBytes=0)

static void	SendToServer (plUInt32 uiSystemID, plUInt32 uiMsgID, plStreamReader &inout_stream, plInt32 iDataBytes=-1)

static void	SendToServer (plTelemetryMessage &ref_msg)

Querying State
static ConnectionMode	GetConnectionMode ()
	Returns whether the telemetry system is set up as Server, Client or not initialized at all.

static bool	IsConnectedToServer ()
	Returns whether a Client has an active connection to a Server.

static bool	IsConnectedToClient ()
	Returns whether a Server has an active connection to at least one Client.

static bool	IsConnectedToOther ()
	Returns whether a connection to another application has been made. Does not differentiate between Server and Client mode.

static plTime	GetPingToServer ()
	Returns the last round trip time ('Ping') to the Server. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static plStringView	GetServerName ()
	Returns the name of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static void	SetServerName (plStringView sName)
	Sets the name of the telemetry server. This is broadcast to connected clients, which can display this string for usability.

static plStringView	GetServerIP ()
	Returns the IP address of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static plUInt32	GetServerID ()
	Returns a 'unique' ID for the application instance to which this Client is connected.

static plMutex &	GetTelemetryMutex ()
	Returns the internal mutex used to synchronize all telemetry data access.

Static Public Attributes
static plUInt16	s_uiPort = 1040
	The port over which plTelemetry will connect.

Friends
class	plTelemetryThread

Processing Messages
using	ProcessMessagesCallback = void ()(void)

static plResult	RetrieveMessage (plUInt32 uiSystemID, plTelemetryMessage &out_message)
	Checks whether any message for the system with the given ID exists and returns that.

static void	UpdateNetwork ()
	Polls the network for new incoming messages and ensures outgoing messages are sent.

static void	AcceptMessagesForSystem (plUInt32 uiSystemID, bool bAccept, ProcessMessagesCallback callback=nullptr, void *pPassThrough=nullptr)

static void	PerFrameUpdate ()
	Call this once per frame to process queued messages and to send the PerFrameUpdate event.

static void	SetOutgoingQueueSize (plUInt32 uiSystemID, plUInt16 uiMaxQueued)
	Specifies how many reliable messages from a system might get queued when no recipient is available yet.

plTelemetry Events
using	plEventTelemetry = plEvent<const TelemetryEventData&, plMutex>

static void	AddEventHandler (plEventTelemetry::Handler handler)
	Adds an event handler that is called for every plTelemetry event.

static void	RemoveEventHandler (plEventTelemetry::Handler handler)
	Removes a previously added event handler.

Detailed Description

Todo: document and test (and finish)

Member Enumeration Documentation

◆ ConnectionMode

enum plTelemetry::ConnectionMode

Defines how the plTelemetry system was configured.

Enumerator
None	Not configured yet, at all.
Server	Set up as a Server, i.e. this is an application that broadcasts information about its current state to one or several Clients.
Client	Set up as a Client, i.e. this is a tool that gathers information from a Server, usually for debugging/inspection use cases.

◆ TransmitMode

enum plTelemetry::TransmitMode

Describes how to send messages.

Enumerator
Reliable	Messages should definitely arrive at the target, if necessary they are send several times, until the target acknowledged it.
Unreliable	Messages are sent at most once, if they get lost, they are not resend. If it is known beforehand, that not receiver exists, they are dropped without sending them at all.

Member Function Documentation

◆ CloseConnection()

void plTelemetry::CloseConnection ( )

static

Closes any connection previously opened using ConnectToServer() or CreateServer().

This will remove all queued incoming and outgoing messages (though it might send some of them still). It will not reset the state of which messages are filtered out or which callbacks to fire.

◆ ConnectToServer()

plResult plTelemetry::ConnectToServer ( plStringView sConnectTo = {} )

static

Starts a connection as a 'Client' to one server.

Parameters

szConnectTo String that contains a host name or IP address to connect to. If empty, 'localhost' is used.

Note: Connections to invalid host names often succeed, because the underlying network API will fall back to 'localhost'. Connections to invalid IP addresses will however always fail.

This function will set the plTelemetry connection mode to 'Client'. This is mutually exclusive with CreateServer().

◆ CreateServer()

void plTelemetry::CreateServer ( )

static

Opens a connection as a server.

Other applications can then connect to this application using ConnectToServer() with the IP of this machine.

◆ GetServerID()

static plUInt32 plTelemetry::GetServerID ( )

inlinestatic

Returns a 'unique' ID for the application instance to which this Client is connected.

Only meaningful if there is an active connection (see IsConnectedToServer() ). This can be used when a connection got lost and a Client had to reconnect to the Server, to check whether the instance that the Client connected to is still the same as before. If it did not change, the application can simply continue gathering data. Otherwise it should clear its state and start from scratch.

◆ GetTelemetryMutex()

plMutex & plTelemetry::GetTelemetryMutex ( )

static

Returns the internal mutex used to synchronize all telemetry data access.

This can be used to block all threads from accessing telemetry data, thus stopping the application. This can be useful when you want to implement some operation that is fully synchronous with some external tool and you want to wait for its response and prevent all other actions while you wait for that.

◆ RetrieveMessage()

plResult plTelemetry::RetrieveMessage	(	plUInt32	uiSystemID,
		plTelemetryMessage &	out_message )

static

Checks whether any message for the system with the given ID exists and returns that.

If no message for the given system is available, PL_FAILURE is returned. This function will not poll the network to check whether new messages arrived. Use UpdateNetwork() and RetrieveMessage() in a loop, if you are waiting for a specific message, to continuously update the network state and check whether the desired message has arrived. However, if you do so, you will be able to deadlock your application, if such a message never arrives. Also it might fill up other message queues which might lead to messages getting discarded.

◆ SetOutgoingQueueSize()

void plTelemetry::SetOutgoingQueueSize	(	plUInt32	uiSystemID,
		plUInt16	uiMaxQueued )

static

Specifies how many reliable messages from a system might get queued when no recipient is available yet.

Parameters

uiSystemID	The ID for the system that sends the messages.
uiMaxQueued	The maximum number of reliable messages that get queued and delivered later, once a proper recipient is available. Set this to zero to discard all messages from a system, when no recipient is available.

The default queue size is 1000. When a connection to a suitable recipient is made, all queued messages are delivered in one burst.

◆ SetServerName()

void plTelemetry::SetServerName ( plStringView sName )

static

Sets the name of the telemetry server. This is broadcast to connected clients, which can display this string for usability.

Usually this would be used to send the application name, to make it easier to see to which app the tool is connected, but setting a custom name can be used to add important details, e.g. whether the app is running in single-player or multi-player mode etc. The server name can be changed at any time.

◆ UpdateNetwork()

void plTelemetry::UpdateNetwork ( )

static

Polls the network for new incoming messages and ensures outgoing messages are sent.

Usually it is not necessary to call this function manually, as a worker thread will do that periodically already. However, if you are waiting for a specific message (see RetrieveMessage() ), you can call this function in a loop together with RetrieveMessage() to wait for that message. In that case it might also make sense to use GetTelemetryMutex() to lock the entire section while waiting for the message.

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

Code/Engine/Foundation/Communication/Telemetry.h
Code/Engine/Foundation/Communication/Implementation/Telemetry.cpp
Code/Engine/Foundation/Communication/Implementation/TelemetryHelpers.cpp
Code/Engine/Foundation/Communication/Implementation/TelemetryThread.cpp
Code/EnginePlugins/InspectorPlugin/InspectorPlugin.cpp

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Friends

Processing Messages

plTelemetry Events

Detailed Description

Member Enumeration Documentation

◆ ConnectionMode

◆ TransmitMode

Member Function Documentation

◆ CloseConnection()

◆ ConnectToServer()

◆ CreateServer()

◆ GetServerID()

◆ GetTelemetryMutex()

◆ RetrieveMessage()

◆ SetOutgoingQueueSize()

◆ SetServerName()

◆ UpdateNetwork()