![]() |
Kodi Documentation 22.0
Kodi is an open source media player and entertainment hub.
|
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. | |
This implements a simple message dispatcher/router for Kodi.
For most users that wants to send message go to the documentation for these
For anyone wanting to implement a message receiver, go to the documentation for
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
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.
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
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
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.
|
default |
KODI::MESSAGING::CApplicationMessenger::~CApplicationMessenger | ( | ) |
void KODI::MESSAGING::CApplicationMessenger::Cleanup | ( | ) |
bool KODI::MESSAGING::CApplicationMessenger::IsProcessThread | ( | ) | const |
Returns true if this is the process / app loop thread.
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.
[in] | messageId | defined further up in this file |
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.
[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 |
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.
[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 |
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.
[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 |
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.
[in] | messageId | defined further up in this file |
[in] | param3 | value depends on the message being sent |
void KODI::MESSAGING::CApplicationMessenger::ProcessMessages | ( | ) |
Called from any thread to dispatch messages.
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.
void KODI::MESSAGING::CApplicationMessenger::RegisterReceiver | ( | IMessageTarget * | target | ) |
This should be called any class implementing.
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.
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). |
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.
[in] | messageId | defined further up in this file |
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.
[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 |
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.
[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 |
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.
[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 |
|
inline |
Set the UI thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.
thread | The UI thread ID |
|
inline |
Set the processing thread id to avoid messenger being dependent on CApplication to determine if marshaling is required.
thread | The processing thread ID |
|
inline |