The MessageThread class implements a thread with a ready to use MessageQueue and MessageDispatch class. More...

#include <murl_util_message_thread.h>

Detailed Description

The MessageThread class implements a thread with a ready to use MessageQueue and MessageDispatch class.

Example for sending data to different methods:

#include "murl_util_message_thread.h"
 
class MyMessage1 : public Util::Message
{
public:
    MyMessage1(UInt32 messageId, UInt32 data)
    : Util::Message(messageId)
    , mData(data)
    {
    }
 
    UInt32 mData;
};
 
class MyMessage2 : public Util::Message
{
public:
    MyMessage2(UInt32 messageId, UInt32 data1, UInt32 data2)
    : Util::Message(messageId)
    {
        mData.Add(data1);
        mData.Add(data2);
    }
 
    Array<UInt32> mData;
};
 
class MyThread : public Util::MessageThread
{
public:
    enum MyMessageIds
    {
        MY_MESSAGE_1,
        MY_MESSAGE_2
    };
 
    MyThread()
    : MessageThread("MyThread")
    {
        Util::MessageDispatch& disp = GetMessageDispatch();
        disp.Register<MyMessage1>(MY_MESSAGE_1, this, &MyThread::Receive1);
        disp.Register<MyMessage2>(MY_MESSAGE_2, this, &MyThread::Receive2);
    }
 
    virtual ~MyThread()
    {
        Stop();
        Join();
    }
 
    void Send1(UInt32 data)
    {
        Debug::Trace(("%s Message1(%d) Send\n"), mName.Begin(), data);
        SendMessage(AutoPointer<MyMessage1>(new MyMessage1(MY_MESSAGE_1, data)));
    }
 
    void Send2(UInt32 data1, UInt32 data2)
    {
        Debug::Trace(("%s Message2(%d, %d) SendSync\n"), mName.Begin(), data1, data2);
        SendSyncMessage(AutoPointer<MyMessage2>(new MyMessage2(MY_MESSAGE_2, data1, data2)));
        Debug::Trace(("%s Message2(%d, %d) returned\n"), mName.Begin(), data1, data2);
    }
 
protected:
    void Receive1(AutoPointer<MyMessage1> message)
    {
        Debug::Trace(("%s Message1(%d) received\n"), mName.Begin(), message->mData);
    }
 
    void Receive2(AutoPointer<MyMessage2> message)
    {
        Debug::Trace(("%s Message2(%d, %d) received\n"), mName.Begin(), message->mData[0], message->mData[1]);
    }
};
 
void MyMain()
{
    MyThread myThread;
    myThread.Start();
 
    myThread.Send2(16, 17);
    myThread.Send1(42);
    myThread.Send2(19, 18);
    myThread.Send1(43);
 
    myThread.SendQuit();
    myThread.Join();
}

Inheritance diagram for Murl::Util::MessageThread:

Public Member Functions
	MessageThread ()
	The default constructor.

	MessageThread (const String &name)
	Constructor taking a thread name. More...

	~MessageThread () override
	The destructor. More...

Bool	Start () override
	Create and start the thread. More...

virtual Bool	Start (const System::Time &timeout)
	Create and start the thread, run the message loop with timeout. More...

void	Stop () override
	Stop the thread. More...

void	SetTimeout (const System::Time &timeout)
	Set the message loop timeout. More...

const System::Time &	GetTimeout () const
	Get the message loop timeout. More...

MessageQueue &	GetMessageQueue ()
	Get the thread's message queue object. More...

MessageDispatch &	GetMessageDispatch ()
	Get the thread's message dispatch object. More...

virtual Bool	SendQuit ()
	Send the ID_QUIT message to the thread. More...

virtual Bool	SendId (UInt32 messageId)
	Send the Message object to the thread. More...

virtual Bool	SendMessage (Message::AutoPtr message)
	Send a message object to the thread. More...

virtual Bool	SendSyncMessage (Message::AutoPtr message)
	Send a message object to the thread and wait until the message is delivered and processed. More...

Public Member Functions inherited from Murl::System::Thread
virtual	~Thread ()
	The destructor.

virtual void	Join ()
	Join and destroy the thread. More...

virtual void	Flush ()
	Flush the autorelease memory pool. More...

virtual UInt64	GetId ()
	Get the thread identifier. More...

Protected Member Functions
virtual MessageQueue::Result	WaitMessage (Message::AutoPtr &message)
	Wait for a message (using Message::ID_ANY). More...

virtual MessageQueue::Result	WaitMessage (Message::AutoPtr &message, const System::Time &timeout)
	Wait for a message with timeout (using Message::ID_ANY). More...

virtual MessageQueue::Result	GetMessage (Message::AutoPtr &message)
	Get a message from the message queue (using Message::ID_ANY). More...

virtual MessageQueue::Result	PeekMessage (const Message *&message)
	Peek a message from the message queue (using Message::ID_ANY). More...

Bool	Run () override
	The System::Thread::Run() method implementation. More...

virtual MessageQueue::Result	DispatchMessage (Message::AutoPtr &message)
	Wait for a message and dispatch the message. More...

virtual MessageQueue::Result	DispatchMessage (Message::AutoPtr &message, const System::Time &timeout)
	Wait for a message and dispatch the message with timeout. More...

Protected Member Functions inherited from Murl::System::Thread
	Thread (const String &name)
	Constructor taking a thread name. More...

Protected Attributes
MessageQueue	mMessageQueue
	The message queue instance.

MessageDispatch	mMessageDispatch
	The message dispatch instance.

System::Time	mTimeout
	The message loop timeout.

Protected Attributes inherited from Murl::System::Thread
Bool	mIsRunning
	The running state of the thread.

String	mName
	The name of the thread.

UInt64	mThreadId
	The identifier of the thread.

ThreadHandle *	mHandle
	The anonymous thread handle for internal use only.

Additional Inherited Members
Public Types inherited from Murl::System::Thread
enum	SchedulingPriority { SCHEDULING_PRIORITY_LOWEST, SCHEDULING_PRIORITY_NORMAL, SCHEDULING_PRIORITY_HIGHEST }
	Thread scheduling priority enumeration. More...

enum	SchedulingPolicy { SCHEDULING_POLICY_OTHER, SCHEDULING_POLICY_FIFO, SCHEDULING_POLICY_ROUND_ROBIN }
	Thread scheduling policy enumeration. More...

Static Public Member Functions inherited from Murl::System::Thread
static Bool	SetCurrentPriority (SchedulingPriority priority, SchedulingPolicy policy=SCHEDULING_POLICY_OTHER)
	Set the current thread's priority and scheduling policy. More...

static Bool	SetCurrentAffinityMask (UInt32 mask)
	Set the current thread's CPU affinity mask. More...

static UInt64	GetCurrentId ()
	Get the current thread identifier. More...

Constructor & Destructor Documentation

◆ MessageThread()

Murl::Util::MessageThread::MessageThread ( const String & name )

Constructor taking a thread name.

Parameters

name	The thread name.

◆ ~MessageThread()

Murl::Util::MessageThread::~MessageThread ( )

override

The destructor.

Calls Stop() and System::Thread::Join().

Member Function Documentation

◆ Start() [1/2]

Bool Murl::Util::MessageThread::Start ( )

overridevirtual

Create and start the thread.

Returns: System::Thread::Start().

Reimplemented from Murl::System::Thread.

◆ Start() [2/2]

virtual Bool Murl::Util::MessageThread::Start ( const System::Time & timeout )

virtual

Create and start the thread, run the message loop with timeout.

If a timeout occurs the message dispatcher timeout method is called which executes the MessageDispatch::RegisterTimeout() callback object.

Parameters

timeout The maximum time to wait for messages.

Returns: System::Thread::Start().

◆ Stop()

void Murl::Util::MessageThread::Stop ( )

overridevirtual

Stop the thread.

Calls SendQuit() and System::Thread::Stop().

Reimplemented from Murl::System::Thread.

◆ SetTimeout()

void Murl::Util::MessageThread::SetTimeout ( const System::Time & timeout )

Set the message loop timeout.

Parameters

timeout The maximum time to wait for messages.

◆ GetTimeout()

const System::Time& Murl::Util::MessageThread::GetTimeout ( ) const

Get the message loop timeout.

Returns: The message loop timeout.

◆ GetMessageQueue()

MessageQueue& Murl::Util::MessageThread::GetMessageQueue ( )

Get the thread's message queue object.

Returns: The thread's message queue object.

◆ GetMessageDispatch()

MessageDispatch& Murl::Util::MessageThread::GetMessageDispatch ( )

Get the thread's message dispatch object.

Returns: The thread's message dispatch object.

◆ SendQuit()

virtual Bool Murl::Util::MessageThread::SendQuit ( )

virtual

Send the ID_QUIT message to the thread.

Returns: true if successful.

◆ SendId()

virtual Bool Murl::Util::MessageThread::SendId ( UInt32 messageId )

virtual

Send the Message object to the thread.

Parameters

messageId The message identifier to send.

Returns: true if successful.

◆ SendMessage()

virtual Bool Murl::Util::MessageThread::SendMessage ( Message::AutoPtr message )

virtual

Send a message object to the thread.

Parameters

message The message object to send.

Returns: true if successful.

◆ SendSyncMessage()

virtual Bool Murl::Util::MessageThread::SendSyncMessage ( Message::AutoPtr message )

virtual

Send a message object to the thread and wait until the message is delivered and processed.

If this method is called from it's own thread context the message is dispatched immediately.

Parameters

message The message object to send.

Returns: true if successful.

◆ WaitMessage() [1/2]

virtual MessageQueue::Result Murl::Util::MessageThread::WaitMessage ( Message::AutoPtr & message )

protectedvirtual

Wait for a message (using Message::ID_ANY).

Parameters

message The message return value. The message returned is removed from the message queue.

Returns: The message queue result.

◆ WaitMessage() [2/2]

virtual MessageQueue::Result Murl::Util::MessageThread::WaitMessage	(	Message::AutoPtr &	message,
		const System::Time &	timeout
	)

protectedvirtual

Wait for a message with timeout (using Message::ID_ANY).

Parameters

message	The message return value. The message returned is removed from the message queue.
timeout	The maximum time to wait.

Returns: The message queue result.

◆ GetMessage()

virtual MessageQueue::Result Murl::Util::MessageThread::GetMessage ( Message::AutoPtr & message )

protectedvirtual

Get a message from the message queue (using Message::ID_ANY).

Parameters

message The message return value. The message returned is removed from the message queue.

Returns: The message queue result.

◆ PeekMessage()

virtual MessageQueue::Result Murl::Util::MessageThread::PeekMessage ( const Message *& message )

protectedvirtual

Peek a message from the message queue (using Message::ID_ANY).

Checks if a message is in the message queue but does not remove the message from the message queue.

Parameters

message The message return value.

Returns: The message queue result.

◆ Run()

Bool Murl::Util::MessageThread::Run ( )

overrideprotectedvirtual

The System::Thread::Run() method implementation.

Implements the message loop:

Bool Util::MessageThread::Run()
{
    while (mIsRunning)
    {
        Message::AutoPtr message;
        MessageQueue::Result result = MessageQueue::FAILED;
        if (mTimeout.IsInfinite())
        {
            result = DispatchMessage(message);
        }
        else
        {
            result = DispatchMessage(message, mTimeout);
        }
        if (result == MessageQueue::RECEIVED)
        {
            if (!message.IsNull())
            {
                Debug::Error("MessageThread '%s': Non-dispatched message id %d received",
                mName.Begin(), message->GetId());
            }
        }
        else if (result == MessageQueue::TIMEOUT)
        {
            mMessageDispatch.ExecuteTimeout();
        }
        else if (result == MessageQueue::QUIT)
        {
            Thread::Stop();
        }
        Flush();
    }
    return true;
}

Returns: true if successful.

Implements Murl::System::Thread.

◆ DispatchMessage() [1/2]

virtual MessageQueue::Result Murl::Util::MessageThread::DispatchMessage ( Message::AutoPtr & message )

protectedvirtual

Wait for a message and dispatch the message.

Parameters

message The message return value.

Returns: The wait message queue result.

◆ DispatchMessage() [2/2]

virtual MessageQueue::Result Murl::Util::MessageThread::DispatchMessage	(	Message::AutoPtr &	message,
		const System::Time &	timeout
	)

protectedvirtual

Wait for a message and dispatch the message with timeout.

Parameters

message	The message return value.
timeout	The maximum time to wait.

Returns: The wait message queue result.

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

murl_util_message_thread.h

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ MessageThread()

◆ ~MessageThread()

Member Function Documentation

◆ Start() [1/2]

◆ Start() [2/2]

◆ Stop()

◆ SetTimeout()

◆ GetTimeout()

◆ GetMessageQueue()

◆ GetMessageDispatch()

◆ SendQuit()

◆ SendId()

◆ SendMessage()

◆ SendSyncMessage()

◆ WaitMessage() [1/2]

◆ WaitMessage() [2/2]

◆ GetMessage()

◆ PeekMessage()

◆ Run()

◆ DispatchMessage() [1/2]

◆ DispatchMessage() [2/2]