juce::MessageManager Class Reference

This class is in charge of the application's event-dispatch loop. More...

#include <juce_MessageManager.h>

Collaboration diagram for juce::MessageManager:

Classes
class	Lock
	A lock you can use to lock the message manager. More...
class	MessageBase
	Internal class used as the base class for all message objects. More...

Public Member Functions
void *	callFunctionOnMessageThread (MessageCallbackFunction *callback, void *userData)
	Calls a function using the message-thread.
bool	currentThreadHasLockedMessageManager () const noexcept
	Returns true if the caller thread has currently got the message manager locked.
void	deregisterBroadcastListener (ActionListener *listener)
	Deregisters a broadcast listener.
Thread::ThreadID	getCurrentMessageThread () const noexcept
	Returns the ID of the current message thread, as set by setCurrentThreadAsMessageThread().
bool	hasStopMessageBeenSent () const noexcept
	Returns true if the stopDispatchLoop() method has been called.
bool	isThisTheMessageThread () const noexcept
	Returns true if the caller-thread is the message thread.
void	registerBroadcastListener (ActionListener *listener)
	Registers a listener to get told about broadcast messages.
void	runDispatchLoop ()
	Runs the event dispatch loop until a stop message is posted.
bool	runDispatchLoopUntil (int millisecondsToRunFor)
	Synchronously dispatches messages until a given time has elapsed.
void	setCurrentThreadAsMessageThread ()
	Called to tell the manager that the current thread is the one that's running the dispatch loop.
void	stopDispatchLoop ()
	Sends a signal that the dispatch loop should terminate.

Static Public Member Functions
static void	broadcastMessage (const String &messageText)
	Sends a message to all other JUCE applications that are running.
template<typename Function >
static bool	callAsync (Function &&function)
	Asynchronously invokes a function or C++11 lambda on the message thread.
template<typename Function >
static auto	callSync (Function &&function) -> CallSyncResult< decltype(function())>
	Similar to callFunctionOnMessageThread(), calls a function on the message thread, blocking the current thread until a result is available.
static void	deleteInstance ()
	Deletes the global MessageManager instance.
static bool	existsAndIsCurrentThread () noexcept
	Returns true if there's an instance of the MessageManager, and if the current thread is running it.
static bool	existsAndIsLockedByCurrentThread () noexcept
	Returns true if there's an instance of the MessageManager, and if the current thread has the lock on it.
static MessageManager *	getInstance ()
	Returns the global instance of the MessageManager.
static MessageManager *	getInstanceWithoutCreating () noexcept
	Returns the global instance of the MessageManager, or nullptr if it doesn't exist.

Private Types
template<typename FunctionResult >
using	CallSyncResult = std::conditional_t< std::is_same_v< FunctionResult, void >, bool, std::optional< FunctionResult > >

Private Member Functions
	MessageManager () noexcept

Static Private Member Functions
static void	doPlatformSpecificInitialisation ()
static void	doPlatformSpecificShutdown ()
static void *	exitModalLoopCallback (void *)
static bool	postMessageToSystemQueue (MessageBase *)
template<typename Function >
static auto	transformResult (Function &&f)

Private Attributes
std::unique_ptr< ActionBroadcaster >	broadcaster
Thread::ThreadID	messageThreadId
std::mutex	messageThreadIdMutex
Atomic< int >	quitMessagePosted { 0 }
Atomic< int >	quitMessageReceived { 0 }
Atomic< Thread::ThreadID >	threadWithLock

Static Private Attributes
static MessageManager *	instance

Friends
class	MessageBase
class	MessageManagerLock
class	QuitMessage

Detailed Description

This class is in charge of the application's event-dispatch loop.

See also

Message, CallbackMessage, MessageManagerLock, JUCEApplication, JUCEApplicationBase

@tags{Events}

Member Typedef Documentation

CallSyncResult

template<typename FunctionResult >

using juce::MessageManager::CallSyncResult = std::conditional_t<std::is_same_v<FunctionResult, void>, bool, std::optional<FunctionResult> >

private

Constructor & Destructor Documentation

MessageManager()

juce::MessageManager::MessageManager ( )

privatenoexcept

Member Function Documentation

broadcastMessage()

static void juce::MessageManager::broadcastMessage ( const String &  messageText )

static

Sends a message to all other JUCE applications that are running.

Parameters

messageText

the string that will be passed to the actionListenerCallback() method of the broadcast listeners in the other app.

See also

registerBroadcastListener, ActionListener

callAsync()

template<typename Function >

static bool juce::MessageManager::callAsync ( Function &&  function )

inlinestatic

Asynchronously invokes a function or C++11 lambda on the message thread.

Parameters

function

the function to call, which should have no arguments

Returns

true if the message was successfully posted to the message queue, or false otherwise.

Referenced by juce::detail::ConcreteScopedContentSharerImpl::handleAsyncUpdate(), and juce::detail::ConcreteScopedMessageBoxImpl::handleAsyncUpdate().

callFunctionOnMessageThread()

void * juce::MessageManager::callFunctionOnMessageThread	(	MessageCallbackFunction *	callback,
		void *	userData
	)

Calls a function using the message-thread.

This can be used by any thread to cause this function to be called-back by the message thread. If it's the message-thread that's calling this method, then the function will just be called; if another thread is calling, a message will be posted to the queue, and this method will block until that message is delivered, the function is called, and the result is returned.

Be careful not to cause any deadlocks with this! It's easy to do - e.g. if the caller thread has a critical section locked, which an unrelated message callback then tries to lock before the message thread gets round to processing this callback.

Parameters

callback	the function to call - its signature must be void* myCallbackFunction (void*)
userData	a user-defined pointer that will be passed to the function that gets called

Returns

the value that the callback function returns.

See also

MessageManagerLock

callSync()

template<typename Function >

static auto juce::MessageManager::callSync ( Function &&  function ) -> CallSyncResult<decltype (function())>

inlinestatic

Similar to callFunctionOnMessageThread(), calls a function on the message thread, blocking the current thread until a result is available.

Be careful not to cause any deadlocks with this! It's easy to do - e.g. if the caller thread has a critical section locked, which an unrelated message callback then tries to lock before the message thread gets round to processing this callback.

Parameters

function

the function to call, which should have no parameters

Returns

if function() returns void, then callSync returns a boolean where 'true' indicates that the function was called successfully, and 'false' indicates that the message could not be posted. if function() returns any other type 'T', then callSync returns std::optional<T>, where the optional value will be valid if the function was called successfully, or nullopt otherwise.

References jassertfalse.

currentThreadHasLockedMessageManager()

bool juce::MessageManager::currentThreadHasLockedMessageManager ( ) const

noexcept

Returns true if the caller thread has currently got the message manager locked.

see the MessageManagerLock class for more info about this.

This will be true if the caller is the message thread, because that automatically gains a lock while a message is being dispatched.

deleteInstance()

static void juce::MessageManager::deleteInstance ( )

static

Deletes the global MessageManager instance.

Does nothing if no instance had been created.

deregisterBroadcastListener()

void juce::MessageManager::deregisterBroadcastListener

(

ActionListener *

listener

)

Deregisters a broadcast listener.

doPlatformSpecificInitialisation()

static void juce::MessageManager::doPlatformSpecificInitialisation ( )

staticprivate

doPlatformSpecificShutdown()

static void juce::MessageManager::doPlatformSpecificShutdown ( )

staticprivate

existsAndIsCurrentThread()

static bool juce::MessageManager::existsAndIsCurrentThread ( )

staticnoexcept

Returns true if there's an instance of the MessageManager, and if the current thread is running it.

existsAndIsLockedByCurrentThread()

static bool juce::MessageManager::existsAndIsLockedByCurrentThread ( )

staticnoexcept

Returns true if there's an instance of the MessageManager, and if the current thread has the lock on it.

exitModalLoopCallback()

static void * juce::MessageManager::exitModalLoopCallback ( void *  )

staticprivate

getCurrentMessageThread()

Thread::ThreadID juce::MessageManager::getCurrentMessageThread ( ) const

inlinenoexcept

Returns the ID of the current message thread, as set by setCurrentThreadAsMessageThread().

(Best to ignore this method unless you really know what you're doing..)

See also

setCurrentThreadAsMessageThread

getInstance()

static MessageManager * juce::MessageManager::getInstance ( )

static

Returns the global instance of the MessageManager.

Referenced by juce::detail::HostDrivenEventLoop::HostDrivenEventLoop(), juce::detail::MessageThread::~MessageThread(), juce::detail::ConcreteScopedContentSharerImpl::handleAsyncUpdate(), juce::detail::ConcreteScopedMessageBoxImpl::handleAsyncUpdate(), juce::detail::HostDrivenEventLoop::processPendingEvents(), and juce::detail::MessageThread::run().

getInstanceWithoutCreating()

static MessageManager * juce::MessageManager::getInstanceWithoutCreating ( )

staticnoexcept

Returns the global instance of the MessageManager, or nullptr if it doesn't exist.

hasStopMessageBeenSent()

bool juce::MessageManager::hasStopMessageBeenSent ( ) const

inlinenoexcept

Returns true if the stopDispatchLoop() method has been called.

isThisTheMessageThread()

bool juce::MessageManager::isThisTheMessageThread ( ) const

noexcept

Returns true if the caller-thread is the message thread.

postMessageToSystemQueue()

static bool juce::MessageManager::postMessageToSystemQueue ( MessageBase *  )

staticprivate

registerBroadcastListener()

void juce::MessageManager::registerBroadcastListener

(

ActionListener *

listener

)

Registers a listener to get told about broadcast messages.

The actionListenerCallback() callback's string parameter is the message passed into broadcastMessage().

See also

broadcastMessage

runDispatchLoop()

void juce::MessageManager::runDispatchLoop

(

)

Runs the event dispatch loop until a stop message is posted.

This method is only intended to be run by the application's startup routine, as it blocks, and will only return after the stopDispatchLoop() method has been used.

See also

stopDispatchLoop

runDispatchLoopUntil()

bool juce::MessageManager::runDispatchLoopUntil

(

int

millisecondsToRunFor

)

Synchronously dispatches messages until a given time has elapsed.

Returns false if a quit message has been posted by a call to stopDispatchLoop(), otherwise returns true.

setCurrentThreadAsMessageThread()

void juce::MessageManager::setCurrentThreadAsMessageThread

(

)

Called to tell the manager that the current thread is the one that's running the dispatch loop.

(Best to ignore this method unless you really know what you're doing..)

See also

getCurrentMessageThread

Referenced by juce::detail::HostDrivenEventLoop::HostDrivenEventLoop(), juce::detail::HostDrivenEventLoop::processPendingEvents(), and juce::detail::MessageThread::run().

stopDispatchLoop()

void juce::MessageManager::stopDispatchLoop

(

)

Sends a signal that the dispatch loop should terminate.

After this is called, the runDispatchLoop() or runDispatchLoopUntil() methods will be interrupted and will return.

See also

runDispatchLoop

Referenced by juce::detail::MessageThread::~MessageThread().

transformResult()

template<typename Function >

static auto juce::MessageManager::transformResult ( Function &&  f )

inlinestaticprivate

Friends And Related Symbol Documentation

MessageBase

friend class MessageBase

friend

MessageManagerLock

friend class MessageManagerLock

friend

QuitMessage

friend class QuitMessage

friend

Member Data Documentation

broadcaster

std::unique_ptr<ActionBroadcaster> juce::MessageManager::broadcaster

private

instance

MessageManager* juce::MessageManager::instance

staticprivate

messageThreadId

Thread::ThreadID juce::MessageManager::messageThreadId

private

messageThreadIdMutex

std::mutex juce::MessageManager::messageThreadIdMutex

mutableprivate

quitMessagePosted

Atomic<int> juce::MessageManager::quitMessagePosted { 0 }

private

quitMessageReceived

Atomic<int> juce::MessageManager::quitMessageReceived { 0 }

private

threadWithLock

Atomic<Thread::ThreadID> juce::MessageManager::threadWithLock

private

---

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

• juce_MessageManager.h