This implements a simple message dispatcher/router for Kodi. More...

#include "messaging/ApplicationMessenger.h"

Public Member Functions
	CApplicationMessenger ()

	~CApplicationMessenger ()

void	Cleanup ()

int	SendMsg (uint32_t messageId)
	Send a blocking message and wait for a response.

int	SendMsg (uint32_t messageId, int param1, int param2=-1, void *payload=nullptr)
	Send a blocking message and wait for a response.

int	SendMsg (uint32_t messageId, int param1, int param2, void *payload, std::string strParam)
	Send a blocking message and wait for a response.

int	SendMsg (uint32_t messageId, int param1, int param2, void *payload, std::string strParam, std::vector< std::string > params)
	Send a blocking message and wait for a response.

void	PostMsg (uint32_t messageId)
	Send a non-blocking message and return immediately.

void	PostMsg (uint32_t messageId, int64_t param3)
	Send a non-blocking message and return immediately.

void	PostMsg (uint32_t messageId, int param1, int param2=-1, void *payload=nullptr)
	Send a non-blocking message and return immediately.

void	PostMsg (uint32_t messageId, int param1, int param2, void *payload, std::string strParam)
	Send a non-blocking message and return immediately.

void	PostMsg (uint32_t messageId, int param1, int param2, void *payload, std::string strParam, std::vector< std::string > params)
	Send a non-blocking message and return immediately.

void	ProcessMessages ()
	Called from any thread to dispatch messages.

void	ProcessWindowMessages ()
	Called from the UI thread to dispatch UI messages This is only of value to implementers of the message pump, do not rely on a specific thread being used other than that it's appropriate for UI messages.

void	SendGUIMessage (const CGUIMessage &msg, int windowID=WINDOW_INVALID, bool waitResult=false)
	Send a GUIMessage, optionally waiting before it's processed to return. This is kept for backward compat and is just a convenience wrapper for for SendMsg and PostMsg specifically for UI messages.

void	RegisterReceiver (IMessageTarget *target)
	This should be called any class implementing.

void	SetGUIThread (const std::thread::id thread)
	Set the UI thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.

void	SetProcessThread (const std::thread::id thread)
	Set the processing thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.

void	Stop ()

bool	IsProcessThread () const
	Returns true if this is the process / app loop thread.

Detailed Description

This implements a simple message dispatcher/router for Kodi.

For most users that wants to send message go to the documentation for these

See also: CApplicationMessenger::SendMsg; CApplicationMessenger::PostMsg

For anyone wanting to implement a message receiver, go to the documentation for

See also: IMessageTarget

IMPLEMENTATION SPECIFIC NOTES - DOCUMENTED HERE FOR THE SOLE PURPOSE OF IMPLEMENTERS OF THIS CLASS On a high level this implements two methods for dispatching messages, SendMsg and PostMsg. These are roughly modeled on the implementation of SendMessage and PostMessage in Windows.

PostMsg is the preferred method to use as it's non-blocking and does not wait for any response before returning to the caller. Messages will be stored in a queue and processed in order.

SendMsg is a blocking version and has a bit more subtleties to it regarding how inter-process dispatching is handled.

Calling SendMsg with a message type that doesn't require marshalling will bypass the message queue and call the receiver directly

Calling SendMsg with a message type that require marshalling to a specific thread when not on that thread will add a message to the queue with a an event, it will then block the calling thread waiting on this event to be signaled. The message will be processed by the correct thread in it's message pump and the event will be signaled, unblocking the calling thread

Calling SendMsg with a message type that require marshalling to a specific thread when already on that thread will behave as scenario one, it will bypass the queue and call the receiver directly.

Currently there is a hack implemented in the message dispatcher that releases the graphicslock before dispatching a message. This was here before the redesign and removing it will require careful inspection of every call site. TODO: add logging if the graphicslock is held during message dispatch

Current design has three different message types

Normal messages that can be processed on any thread
GUI messages that require marshalling to the UI thread
A thread message that will spin up a background thread and wait a specified amount of time before posting the message This should probably be removed, it's left for compatibility

Heavy emphasis on current design, the idea is that we can easily add more message types to route messages to more threads or other scenarios.

See also: CApplicationMessenger::ProcessMessages() handles regular messages that require no marshalling, this can be called from any thread to drive the message pump; CApplicationMessenger::ProcessWindowMessages() handles GUI messages and currently should only be called on the UI thread

If/When this is expanded upon ProcessMessage() and ProcessWindowMessages() should be combined into a single method taking an enum or similar to indicate which message it's interested in.

The above methods are backed by two messages queues, one for each type of message. If more types are added this might need to be redesigned to simplify the lookup of the correct message queue but currently they're implemented as two member variables

The design is meant to be very encapsulated and easy to extend without altering the public interface. e.g. If GUI messages should be handled on another thread, call

See also: CApplicationMessenger::ProcessWindowMessage() on that thread and nothing else has to change. The callers have no knowledge of how this is implemented.

The design is also meant to be very dependency free to work as a bridge between lower layer functionality without having to have knowledge of the GUI or having a dependency on the GUI in any way. This is not the reality currently as this depends on

See also: CApplication and the graphicslock but should be fixed soon enough.

To keep things simple the current implementation routes messages based on a mask that the receiver provides. Any message fitting that mask will be routed to that specific receiver. This will likely need to change if many different receivers are added but it should be possible to do it without any of the callers being changed.

Constructor & Destructor Documentation

◆ CApplicationMessenger()

KODI::MESSAGING::CApplicationMessenger::CApplicationMessenger ( )

default

◆ ~CApplicationMessenger()

KODI::MESSAGING::CApplicationMessenger::~CApplicationMessenger ( )

Member Function Documentation

◆ Cleanup()

void KODI::MESSAGING::CApplicationMessenger::Cleanup ( )

◆ IsProcessThread()

bool KODI::MESSAGING::CApplicationMessenger::IsProcessThread ( ) const

Returns true if this is the process / app loop thread.

◆ PostMsg() [1/5]

void KODI::MESSAGING::CApplicationMessenger::PostMsg ( uint32_t messageId )

Send a non-blocking message and return immediately.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Parameters

[in] messageId defined further up in this file

◆ PostMsg() [2/5]

void KODI::MESSAGING::CApplicationMessenger::PostMsg	(	uint32_t	messageId,
		int	param1,
		int	param2,
		void *	payload,
		std::string	strParam )

Send a non-blocking message and return immediately.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent
[in,out]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message
[in]	strParam	value depends on the message being sent, remains for backward compat

◆ PostMsg() [3/5]

void KODI::MESSAGING::CApplicationMessenger::PostMsg	(	uint32_t	messageId,
		int	param1,
		int	param2,
		void *	payload,
		std::string	strParam,
		std::vector< std::string >	params )

Send a non-blocking message and return immediately.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent
[in,out]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message
[in]	strParam	value depends on the message being sent, remains for backward compat
[in]	params	value depends on the message being sent, kept for backward compatibility

◆ PostMsg() [4/5]

void KODI::MESSAGING::CApplicationMessenger::PostMsg	(	uint32_t	messageId,
		int	param1,
		int	param2 = -1,
		void *	payload = nullptr )

Send a non-blocking message and return immediately.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent
[in,out]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message

◆ PostMsg() [5/5]

void KODI::MESSAGING::CApplicationMessenger::PostMsg	(	uint32_t	messageId,
		int64_t	param3 )

Send a non-blocking message and return immediately.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Parameters

[in]	messageId	defined further up in this file
[in]	param3	value depends on the message being sent

◆ ProcessMessages()

void KODI::MESSAGING::CApplicationMessenger::ProcessMessages ( )

Called from any thread to dispatch messages.

◆ ProcessWindowMessages()

void KODI::MESSAGING::CApplicationMessenger::ProcessWindowMessages ( )

Called from the UI thread to dispatch UI messages This is only of value to implementers of the message pump, do not rely on a specific thread being used other than that it's appropriate for UI messages.

◆ RegisterReceiver()

void KODI::MESSAGING::CApplicationMessenger::RegisterReceiver ( IMessageTarget * target )

This should be called any class implementing.

See also: IMessageTarget before it can receive any messages

◆ SendGUIMessage()

void KODI::MESSAGING::CApplicationMessenger::SendGUIMessage	(	const CGUIMessage &	msg,
		int	windowID = WINDOW_INVALID,
		bool	waitResult = false )

Send a GUIMessage, optionally waiting before it's processed to return. This is kept for backward compat and is just a convenience wrapper for for SendMsg and PostMsg specifically for UI messages.

Parameters

msg	the GUIMessage to send.
windowID	optional window to send the message to (defaults to no specified window).
waitResult	whether to wait for the result (defaults to false).

◆ SendMsg() [1/4]

int KODI::MESSAGING::CApplicationMessenger::SendMsg ( uint32_t messageId )

Send a blocking message and wait for a response.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Under no circumestances shall the caller hold a lock when calling SendMsg as there's no guarantee what the receiver will do to answer the request.

Parameters

[in] messageId defined further up in this file

Returns: meaning of the return varies based on the message

◆ SendMsg() [2/4]

int KODI::MESSAGING::CApplicationMessenger::SendMsg	(	uint32_t	messageId,
		int	param1,
		int	param2,
		void *	payload,
		std::string	strParam )

Send a blocking message and wait for a response.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Under no circumestances shall the caller hold a lock when calling SendMsg as there's no guarantee what the receiver will do to answer the request.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent
[in,out]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message
[in]	strParam	value depends on the message being sent, remains for backward compat

Returns: meaning of the return varies based on the message

◆ SendMsg() [3/4]

int KODI::MESSAGING::CApplicationMessenger::SendMsg	(	uint32_t	messageId,
		int	param1,
		int	param2,
		void *	payload,
		std::string	strParam,
		std::vector< std::string >	params )

Send a blocking message and wait for a response.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Under no circumestances shall the caller hold a lock when calling SendMsg as there's no guarantee what the receiver will do to answer the request.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent
[in,out]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message
[in]	strParam	value depends on the message being sent, remains for backward compat
[in]	params	value depends on the message being sent, kept for backward compatibility

Returns: meaning of the return varies based on the message

◆ SendMsg() [4/4]

int KODI::MESSAGING::CApplicationMessenger::SendMsg	(	uint32_t	messageId,
		int	param1,
		int	param2 = -1,
		void *	payload = nullptr )

Send a blocking message and wait for a response.

If and what the response is depends entirely on the message being sent and should be documented on the message.

Under no circumestances shall the caller hold a lock when calling SendMsg as there's no guarantee what the receiver will do to answer the request.

Parameters

[in]	messageId	defined further up in this file
[in]	param1	value depends on the message being sent
[in]	param2	value depends on the message being sent, defaults to -1
[in]	payload	this is a void pointer that is meant to send larger objects to the receiver what to send depends on the message

Returns: meaning of the return varies based on the message

◆ SetGUIThread()

void KODI::MESSAGING::CApplicationMessenger::SetGUIThread ( const std::thread::id thread )

inline

Set the UI thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.

Parameters

thread The UI thread ID

◆ SetProcessThread()

void KODI::MESSAGING::CApplicationMessenger::SetProcessThread ( const std::thread::id thread )

inline

Set the processing thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.

Parameters

thread The processing thread ID

◆ Stop()

void KODI::MESSAGING::CApplicationMessenger::Stop ( )

inline

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CApplicationMessenger()

◆ ~CApplicationMessenger()

Member Function Documentation

◆ Cleanup()

◆ IsProcessThread()

◆ PostMsg() [1/5]

◆ PostMsg() [2/5]

◆ PostMsg() [3/5]

◆ PostMsg() [4/5]

◆ PostMsg() [5/5]

◆ ProcessMessages()

◆ ProcessWindowMessages()

◆ RegisterReceiver()

◆ SendGUIMessage()

◆ SendMsg() [1/4]

◆ SendMsg() [2/4]

◆ SendMsg() [3/4]

◆ SendMsg() [4/4]

◆ SetGUIThread()

◆ SetProcessThread()

◆ Stop()