Message dispatcher. More...

#include <kanzi/platform/platform.hpp>
#include <kanzi/platform/chrono.hpp>
#include <kanzi/object/metaclass.hpp>
#include <kanzi/message/message_type.hpp>
#include <kanzi/message/message_arguments.hpp>
#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <kanzi/platform/memory.hpp>
#include "kzu_message_dispatcher_properties.h"

Classes
struct	kanzi::TimerMessageArguments

class	kanzi::MessageDispatcherProperties

class	kanzi::MessageDispatcherProperties::WriteLogMessageArguments

class	kanzi::MessageDispatcherProperties::TimerMessageArguments

Namespaces
	kanzi

Macros
#define	KZU_MESSAGE_DISPATCHER_NO_LIMIT
	A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used. More...

Typedefs
typedef kzsError(*	KzuMessageHandlerFunction )(struct kanzi::MessageArguments message, void userData)
	Message callback prototype. More...

typedef kzsError(*	KzuMessageDispatchFunction )(const kanzi::MessageArguments message, void userData)
	Application message callback prototype. More...

typedef function< void(const TimerMessageArguments &)>	kanzi::TimerFunction

typedef shared_ptr< void >	kanzi::TimerSubscriptionToken

Enumerations
enum	KzuTimerMessageMode { KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT, KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH }
	Timer mode. More...

Functions
KANZI_API kzsError	kzuMessageDispatcherCreate (const struct KzcMemoryManager memoryManager, struct KzuMessageDispatcher *out_messageDispatcher)
	Create a message dispatcher. More...

KANZI_API kzsError	kzuMessageDispatcherDelete (struct KzuMessageDispatcher *messageDispatcher)
	Destroy a message dispatcher. More...

KANZI_API void	kzuMessageDispatcherSetInputManager (struct KzuMessageDispatcher messageDispatcher, kanzi::KzuInputManager inputManager)
	Set an input manager for a dispatcher. More...

KANZI_API struct kanzi::KzuInputManager *	kzuMessageDispatcherGetInputManager (const struct KzuMessageDispatcher *messageDispatcher)
	Get the input manager from a dispatcher. More...

KANZI_API void	kzuMessageDispatcherSetTaskScheduler (struct KzuMessageDispatcher messageDispatcher, struct KzuTaskScheduler taskScheduler)
	Set a task scheduler for a dispatcher. More...

KANZI_API struct KzuTaskScheduler *	kzuMessageDispatcherGetTaskScheduler (const struct KzuMessageDispatcher *messageDispatcher)
	Get the task scheduler from a dispatcher. More...

KANZI_API void	kzuMessageDispatcherSetMessageLimit (struct KzuMessageDispatcher *messageDispatcher, kzUint limitThreshold, kzUint limitPerFrame)
	Sets the limitation of how many messages can be processed per frame. More...

KANZI_API kzsError	kzuMessageDispatcherAddHandler (const struct KzuMessageDispatcher messageDispatcher, kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, kanzi::Node messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler. More...

KANZI_API kzsError	kzuMessageDispatcherAddTunnellingHandler (const struct KzuMessageDispatcher messageDispatcher, kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, kanzi::Node messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler for tunneling phase. More...

KANZI_API kzsError	kzuMessageDispatcherIsHandlerSubscriptionValid (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, KzuMessageHandlerFunction handlerFunction, const void userData, kzBool *out_valid)
	Checks if a handler subscription is valid. More...

KANZI_API kzsError	kzuMessageDispatcherRemoveHandler (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, KzuMessageHandlerFunction handlerFunction, const void userData)
	Removes a message handler. More...

KANZI_API kzsError	kzuMessageDispatcherDispatchMessage (struct KzuMessageDispatcher messageDispatcher, struct kanzi::MessageArguments message, kanzi::Node *source)
	Dispatches a message. More...

KANZI_API kzsError	kzuMessageDispatcherDispatchMessageAsync_internal (struct KzuMessageDispatcher messageDispatcher, struct kanzi::MessageArguments message, kanzi::Node *source)
	Dispatches a message. More...

KANZI_API kzsError	kzuMessageDispatcherDispatchQueuedMessages (struct KzuMessageDispatcher *messageDispatcher, kzUint elapsedTime=0)
	Dispatches queued messages. More...

KANZI_API kzsError	kzuMessageDispatcherNotifyObjectDeleted (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node objectNode)
	Notifies the message dispatcher that an object node is being destroyed. More...

KANZI_API kzsError	kzuMessageDispatcherAddTimerHandler (KzuMessageDispatcher messageDispatcher, kzUint interval, enum KzuTimerMessageMode mode, KzuMessageHandlerFunction handlerFunction, void userData)
	Registers a timer handler. More...

KANZI_API kzsError	kzuMessageDispatcherRemoveTimerHandler (KzuMessageDispatcher messageDispatcher, KzuMessageHandlerFunction handlerFunction, const void userData)
	Unregisters a timer handler. More...

KANZI_API kzUint	kzuMessageDispatcherGetTime (const struct KzuMessageDispatcher *messageDispatcher)
	Returns current time of message dispatcher in milliseconds. More...

KANZI_API TimerSubscriptionToken	kanzi::addTimerHandler (KzuMessageDispatcher *messageDispatcher, chrono::milliseconds interval, KzuTimerMessageMode mode, TimerFunction callback)

KANZI_API void	kanzi::removeTimerHandler (KzuMessageDispatcher *messageDispatcher, TimerSubscriptionToken token)

Detailed Description

Message dispatcher.

Provides a system to exchange messages between different parts of an application. Messages can be used to notify of an event or request operations and data.

Macro Definition Documentation

#define KZU_MESSAGE_DISPATCHER_NO_LIMIT

A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used.

Typedef Documentation

typedef kzsError(* KzuMessageHandlerFunction)(struct kanzi::MessageArguments *message, void *userData)

Message callback prototype.

typedef kzsError(* KzuMessageDispatchFunction)(const kanzi::MessageArguments *message, void *userData)

Application message callback prototype.

Enumeration Type Documentation

enum KzuTimerMessageMode

Timer mode.

Enumerator

KZU_TIMER_MESSAGE_MODE_ONCE

Timer will be called once after the specified interval elapses.

Unsubscribe still needed.

KZU_TIMER_MESSAGE_MODE_REPEAT

Timer will be called repeatedly at specified intervals.

Timers in this mode should be disabled when the application update cycle is called infrequently, for example in low power situations, as this generates excessive number of messages.

KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH

Same as KZU_TIMER_MESSAGE_MODE_REPEAT, but the system dispatches only the last message when a timer has several pending messages.

Function Documentation

KANZI_API kzsError kzuMessageDispatcherCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuMessageDispatcher **	out_messageDispatcher
	)

Create a message dispatcher.

KANZI_API kzsError kzuMessageDispatcherDelete ( struct KzuMessageDispatcher * messageDispatcher )

Destroy a message dispatcher.

KANZI_API void kzuMessageDispatcherSetInputManager	(	struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::KzuInputManager *	inputManager
	)

Set an input manager for a dispatcher.

KANZI_API struct kanzi::KzuInputManager* kzuMessageDispatcherGetInputManager ( const struct KzuMessageDispatcher * messageDispatcher )

Get the input manager from a dispatcher.

KANZI_API void kzuMessageDispatcherSetTaskScheduler	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuTaskScheduler *	taskScheduler
	)

Set a task scheduler for a dispatcher.

KANZI_API struct KzuTaskScheduler* kzuMessageDispatcherGetTaskScheduler ( const struct KzuMessageDispatcher * messageDispatcher )

Get the task scheduler from a dispatcher.

KANZI_API void kzuMessageDispatcherSetMessageLimit	(	struct KzuMessageDispatcher *	messageDispatcher,
		kzUint	limitThreshold,
		kzUint	limitPerFrame
	)

Sets the limitation of how many messages can be processed per frame.

If the number of messages exceeds limitThreshold, a warning is logged and the remaining messages are discarded. KZU_MESSAGE_DISPATCHER_NO_LIMIT disables the limitation (default). After the threshold has been exceeded once, subsequent frames will process at most limitPerFrame messages to ensure good framerate.

KANZI_API kzsError kzuMessageDispatcherAddHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		kanzi::Node *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler.

Parameters

messageDispatcher	The message dispatcher to use.
subscriptionSiteNode	Object node that is associated with the message subscription created by this function.
messageType	Type of the message to match.
messageSource	Source of the message (as returned by kzuMessageGetSource) to match.
handlerFunction	Function to call when a matching message appears.
userData	User data pointer passed to handlerFunction.

KANZI_API kzsError kzuMessageDispatcherAddTunnellingHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		kanzi::Node *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler for tunneling phase.

KANZI_API kzsError kzuMessageDispatcherIsHandlerSubscriptionValid	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData,
		kzBool *	out_valid
	)

Checks if a handler subscription is valid.

KANZI_API kzsError kzuMessageDispatcherRemoveHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Removes a message handler.

KANZI_API kzsError kzuMessageDispatcherDispatchMessage	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct kanzi::MessageArguments *	message,
		kanzi::Node *	source
	)

Dispatches a message.

The associated handlers are called immediately.

KANZI_API kzsError kzuMessageDispatcherDispatchMessageAsync_internal	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct kanzi::MessageArguments *	message,
		kanzi::Node *	source
	)

Dispatches a message.

The associated handlers are called when kzuMessageDispatcherDispatchQueuedMessages is called.

KANZI_API kzsError kzuMessageDispatcherDispatchQueuedMessages	(	struct KzuMessageDispatcher *	messageDispatcher,
		kzUint	elapsedTime = `0`
	)

Dispatches queued messages.

Generally should be called once per frame.

KANZI_API kzsError kzuMessageDispatcherNotifyObjectDeleted	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	objectNode
	)

Notifies the message dispatcher that an object node is being destroyed.

This will cancel all messages where the specified node is the source of the message or the current site during routing.

KANZI_API kzsError kzuMessageDispatcherAddTimerHandler	(	KzuMessageDispatcher *	messageDispatcher,
		kzUint	interval,
		enum KzuTimerMessageMode	mode,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Registers a timer handler.

Parameters

messageDispatcher	The message dispatcher to use.
interval	timeout in milliseconds in case of a one-shot timer, and the interval in case of a repeating timer.
mode	KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT or KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH. KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH is recommended for a repeating timer because it calls handlerFunction only once when the interval has been exceeded several times over.
handlerFunction	The function to call when the timer expires.
userData	User data pointer passed to handlerFunction.

KANZI_API kzsError kzuMessageDispatcherRemoveTimerHandler	(	KzuMessageDispatcher *	messageDispatcher,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Unregisters a timer handler.

KANZI_API kzUint kzuMessageDispatcherGetTime ( const struct KzuMessageDispatcher * messageDispatcher )

Returns current time of message dispatcher in milliseconds.

Classes

Namespaces

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation