Updated Nov 06, 2009 by igagis
Labels:	Featured

tingUsageTutorial

ting library usage tutorial

Debugging

For debug builds one needs to define the DEBUG macro. When DEBUG macro is defined ting will do additional checks and assertions which slightly decrease the performance, but for that you will be warned if something goes wrong meaning that there is some bug in the program. For release builds just do not define the DEBUG macro.

Note: for g++ compiler macro can be defined by supplying the -DDEBUG key to the g++.

Creating a Thread

first of all we need to include ting header to use the library

#include <ting/Thread.hpp>

After that we can start using the library. To create a thread one needs to derive a new class representing her thread from ting::Thread base class and override its ting::Thread::Run() method

class MyThread : public ting::Thread{
    //define some variables specific to your thread,
    //in this example we have two ints: a and b
    int a;
    int b;

public:
    //override
    void Run(){
        //do some thread actions
    };
};

After we have our thread class defined we can create an object of this class and start the thread execution by calling ting::Thread::Start() method on it

MyThread thr; //create an object on the stack for simplicity
thr.Start();//start thread execution

After starting the thread we can wait for it to finish its execution by calling ting::Thread::Join() method on the thread object. After this call we can surely say that thread has finished its execution

thr.Join();

Messages and Message Queues

Every thread object has its own message queue (ting::Thread::queue), thus the thread can receive and handle messages from other threads.

Typical implementation of the ting::Thread::Run() method which handles messages looks as follows

void MyThread::Run(){
    while(!this->quitFlag){
        ting::Ptr<ting::Message> m = this->queue.GetMsg();
        m->Handle();
    }
};

This example uses ting::Queue::GetMsg() to retrieve messages from the queue, GetMsg() blocks execution if there are no messages on the queue until some message arrives.

It is also possible to use ting::Queue::PeekMsg() which does not block execution, then typical implementation of Run() method would look as follows

void MyThread::Run(){
    while(!this->quitFlag){
        //handle all messages on the queue
        while(ting::Ptr<ting::Message> m = this->queue.PeekMsg()){
            m->Handle();
        }
        //do some actions to be done every cycle
        //...
    }
};

Note that each thread object has a quitFlag volatile member variable which serves as a convenient indicator to the thread showing when the thread should finish its execution.

Note that ting::QuitMessage will set the quitFlag when it is handled.

Creating your own message

A Message is a mean to ask some thread to execute some code fragment. To do this one needs to create his/her own message (implementing its handler, i.e define the code fragment we want other to execute) and send it to the threads queue.

Let's define our own message class deriving it from ting::Message

class MyMessage : public ting::Message{
    MyThread *myThr;
public:
    MyMessage(MyThread *mt) :
            myThr(mt)
    {
        //assert that this->myThr is not 0.
        //...
    };

    //override
    void Handle(){
        //implement handler for this message
        this->myThr->a = 10;
        this->myThr->b = 20;
    };
};

Now, we can send this message to the thread's queue

//Create and start the thread we're going to send the message to
MyThread thread;
thread.Start();

//create the message
ting::Ptr<ting::Message> msg( new MyMessage(&thread) );

//send the message
thread.PushMessage(msg);

Note that our Handle() method accesses private variables of the thread, so one should probably add a friend declaration to the MyThread class to indicate that MyMessage is a friend of MyThread class and can access its private variables. This will also ideologically indicate that MyThread can handle messages of type MyMessage.

Comment by alex.barry, Aug 13, 2009

I've been tinkering with your headers, and I've got a small issue when I'm making a class for my thread.

class mythread : public ting::Thread { public:

void Run() { / ... / }

};

when I do: mythread thread;

I get an error saying that there is no default constructor.

Naturally, I did this:

mythread::mythread() :

ting::Thread()

{ }

and that worked, but I didn't want to fidget with your code in case I messed something up.

Is this a known bug?

Comment by igagis, Aug 14, 2009

Hi Alex,

it works fine for me, please provide exact code which is not working for you.