BlackLib::BlackThread Class Referenceabstract

Interface class for user specific thread class. More...

#include <BlackThread.h>

Public Types

enum  state {
  Stateless = 0,
  Running = 1,
  Stopped = 2,
  Paused = 3
}
 
enum  priority {
  PriorityDEFAULT = -1,
  PriorityLOWEST = 0,
  PriorityLOW = 1,
  PriorityNORMAL = 2,
  PriorityHIGH = 3,
  PriorityHIGHEST = 4
}
 

Public Member Functions

 BlackThread ()
 Constructor of BlackThread class. More...
 
virtual ~BlackThread ()
 Destructor of BlackThread class. More...
 
BlackThread::priority setPriority (BlackThread::priority tp)
 Changes the priority of thread. More...
 
BlackThread::priority getPriority ()
 Exports the priority of thread. More...
 
const pthread_t getThreadId ()
 Exports the thread native id. More...
 
void run ()
 Runs thread. More...
 
void stop ()
 Stops thread execution. More...
 
void waitUntilFinish ()
 Waits thread until it finished. More...
 
bool isRunning ()
 Exports thread's run state. More...
 
bool isFinished ()
 Exports thread's finish state. More...
 
void pause ()
 Pauses thread execution. More...
 

Static Public Member Functions

static void sleep (unsigned int sec)
 Sleeps the thread for specified second(s). More...
 
static void msleep (unsigned int msec)
 Sleeps the thread for specified milisecond(s). More...
 
static void usleep (unsigned int usec)
 Sleeps the thread for specified microsecond(s). More...
 
static void yield ()
 Yields thread. More...
 

Private Member Functions

virtual void onStopHandler ()
 Thread's stop handler function. More...
 
virtual void onPauseHandler ()
 Thread's pause handler function. More...
 
virtual void onResumeHandler ()
 Thread's resume handler function. More...
 
virtual void onStartHandler ()=0
 Thread's start handler function. More...
 
bool setAttribute (pthread_attr_t *attr, BlackThread::priority tp)
 Sets thread's priority properties to posix type property holder. More...
 
void calculatePriorities ()
 Calculates OS depend priorty values. More...
 

Static Private Member Functions

static void cleanUp (void *thread)
 Thread's exit function. More...
 
static void * threadFunction (void *thread)
 Thread's main function. More...
 

Private Attributes

bool isCreated
 is used to hold the thread is created or not More...
 
pthread_t nativeThread
 is used to hold the thread's posix id More...
 
BlackThread::state threadState
 is used to hold the thread state More...
 
BlackThread::priority threadPriority
 is used to hold the thread priority More...
 
std::vector< int > priorities
 is used to hold the OS based calculated priority values More...
 

Detailed Description

Interface class for user specific thread class.

This class is the base class of the user defined thread class. This class includes all functions which are necessary for the basic thread struct. This class is a pure abstract class so users can't instantiate object from it. Users have to derive their own class(es) from the BlackThread class and they have to re-implement or override some functions. This class uses pthread on the base so it is compatible with multiplatforms.

Example
EXAMPLE PROJECT FILE TREE:

    myThreadProject
     |-> src
         |-> BlackLib
             |-> BlackDirectory
                 |-> BlackDirectory.cpp
                 |-> BlackDirectory.h
             |-> BlackThread
                 |-> BlackThread.cpp
                 |-> BlackThread.h
             |-> BlackMutex
                 |-> BlackMutex.cpp
                 |-> BlackMutex.h
             |-> BlackTime
                 |-> BlackTime.cpp
                 |-> BlackTime.h
             |-> BlackADC
                 |-> BlackADC.cpp
                 |-> BlackADC.h
             |-> BlackGPIO
                 |-> BlackGPIO.cpp
                 |-> BlackGPIO.h
             |-> BlackI2C
                 |-> BlackI2C.cpp
                 |-> BlackI2C.h
             |-> BlackPWM
                 |-> BlackPWM.cpp
                 |-> BlackPWM.h
             |-> BlackSPI
                 |-> BlackSPI.cpp
                 |-> BlackSPI.h
             |-> BlackUART
                 |-> BlackUART.cpp
                 |-> BlackUART.h
             |-> BlackCore.cpp
             |-> BlackCore.h
             |-> BlackDef.h
             |-> BlackErr.h
             |-> BlackLib.h
        |-> myThreadProject.cpp


If BlackLib source files are located in your project like above example project file tree, you have to include BlackThread.h or another source files with adding this line to your project file (myThreadProject.cpp at the example):
#include "BlackLib/BlackThread/BlackThread.h"


If BlackLib source files are located at same level with your project file (myThreadProject.cpp at the example), you have to include BlackThread.h or another source files with adding this line to your project file:

// Filename: myThreadProject.cpp
// Author: Yiğit Yüce - ygtyce@gmail.com
#include <iostream>
#include "BlackLib/BlackThread/BlackThread.h"
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
// do some other things here
return 0;
}


You can use "using namespace BlackLib" also. You can get rid of writing "BlackLib::", with using this method.
// Filename: myThreadProject.cpp
// Author: Yiğit Yüce - ygtyce@gmail.com
#include <iostream>
#include "BlackLib/BlackThread/BlackThread.h"
using namespace BlackLib;
class Task1 : public BlackThread
{
public:
{
// do something here
}
{
// do something here
}
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
// do some other things here
return 0;
}

Member Enumeration Documentation

This enum is used to define thread's priority.

Enumerator
PriorityDEFAULT 

enumeration for default priority thread

PriorityLOWEST 

enumeration for lowest priority thread

PriorityLOW 

enumeration for low priority thread

PriorityNORMAL 

enumeration for normal priority thread

PriorityHIGH 

enumeration for high priority thread

PriorityHIGHEST 

enumeration for highest priority thread

This enum is used to define thread's current state.

Enumerator
Stateless 

enumeration for stateless state thread

Running 

enumeration for running state thread

Stopped 

enumeration for stopped state thread

Paused 

enumeration for paused state thread

Constructor & Destructor Documentation

BlackLib::BlackThread::BlackThread ( )

Constructor of BlackThread class.

This function sets the thread state to "stateless", thread priority to "default" and calculates platform depend priority values. This function calls when the users derived class is instantiated.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
t1->run();
return 0;
}
See also
calculatePriorities()
BlackLib::BlackThread::~BlackThread ( )
virtual

Destructor of BlackThread class.

Member Function Documentation

void BlackLib::BlackThread::calculatePriorities ( )
private

Calculates OS depend priorty values.

This function's mission is to do some background job and users should not call this function directly.

See also
priorities
void BlackLib::BlackThread::cleanUp ( void *  thread)
staticprivate

Thread's exit function.

This function calls onStopHandler() function when it called by posix thread's cleanup system.

This function's mission is to do some background job and users should not call this function directly.

See also
onStopHandler()
BlackThread::priority BlackLib::BlackThread::getPriority ( )

Exports the priority of thread.

Returns
Current thread priority.
Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
t1->run();
std::cout << "current thread priority: " << t1->getPriority();
return 0;
}
// Possible Output:
// current thread priority: 4
const pthread_t BlackLib::BlackThread::getThreadId ( )

Exports the thread native id.

Returns
thread id.
Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
std::cout << "Current thread id: " << t1->getThreadId();
t1->run();
std::cout << "Current thread id: " << t1->getThreadId();
return 0;
}
// Possible Output:
// Current thread id: 0
// Current thread id: 46231
bool BlackLib::BlackThread::isFinished ( )

Exports thread's finish state.

Returns
true if thread's state is "stopped" else false.
Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
if( t1->isFinished() )
{
t1->run();
}
return 0;
}
bool BlackLib::BlackThread::isRunning ( )

Exports thread's run state.

Returns
true if thread's state is "running" or "paused" else false.
Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
if( t1->isRunning() )
{
t1->stop();
}
return 0;
}
void BlackLib::BlackThread::msleep ( unsigned int  msec)
static

Sleeps the thread for specified milisecond(s).

Parameters
[in]msectime in miliseconds
Example
std::cout << "Main is a thread also and it will sleep 2000 miliseconds now." << std::endl;
std::cout << "Main thread woke up." << std::endl;
// Possible Output:
// Main is a thread also and it will sleep 2000 miliseconds now.
// Main thread woke up.
void BlackLib::BlackThread::onPauseHandler ( )
privatevirtual

Thread's pause handler function.

This function should overload at user's derived class. This function calls from pause() function. Users should not call this function directly.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
this->pause();
// do something here
}
{
// do something here
}
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
pause()
void BlackLib::BlackThread::onResumeHandler ( )
privatevirtual

Thread's resume handler function.

This function should overload at user's derived class. This function calls from pause() function. Users should not call this function directly.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
this->pause();
// do something here
}
{
// do something here
}
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
pause()
virtual void BlackLib::BlackThread::onStartHandler ( )
privatepure virtual

Thread's start handler function.

This function has to overload at user's derived class. This function calls from threadFunction() function and the threadFunction() calls from run() function. Users should not call this function directly.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
threadFunction()
run()
void BlackLib::BlackThread::onStopHandler ( )
privatevirtual

Thread's stop handler function.

This function should overload at user's derived class. This function calls from cleanUp() function. Users should not call this function directly.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
cleanUp()
stop()
void BlackLib::BlackThread::pause ( )

Pauses thread execution.

Actually this function calls onPauseHandler() and then calls onResumeHandler() function only. Users should define the behaviour of thread when this function called(thread paused), by overloading onPauseHandler() and onResumeHandler() function on theirs own derived class. If users did not overload this/these function(s) on derived class, this function does nothing.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
this->pause();
// do something here
}
{
// do something here
}
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
onPauseHandler()
onResumeHandler()
void BlackLib::BlackThread::run ( )

Runs thread.

This function creates and runs the thread if it's state is "stateless" or "stopped". All thread's entry point is BlackThread::threadFunction() function. This entry point function runs the onStartHandler() function in users derived class, after some preparation processes.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
return 0;
}
See also
threadFunction()
onStartHandler()
bool BlackLib::BlackThread::setAttribute ( pthread_attr_t *  attr,
BlackThread::priority  tp 
)
private

Sets thread's priority properties to posix type property holder.

This function calls from the run() function only. While the thread is creating, thread create function wants posix type property holder struct as parameter. This function is used for initializing this struct with given priorty. In run() function, thread will be created with this struct after initialized this struct.

Actually this function's mission is to do some background job and users should not call this function directly.

Returns
true if setting is successful else false.
See also
run()
BlackThread::priority BlackLib::BlackThread::setPriority ( BlackThread::priority  tp)

Changes the priority of thread.

This function changes the thread's priority if the user's platform is allowed for this operation.

Parameters
[in]tpnew thread priority
Returns
Current thread priority.
Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
t1->run();
return 0;
}
void BlackLib::BlackThread::sleep ( unsigned int  sec)
static

Sleeps the thread for specified second(s).

Parameters
[in]sectime in seconds
Example
std::cout << "Main is a thread also and it will sleep 2 seconds now." << std::endl;
std::cout << "Main thread woke up." << std::endl;
// Possible Output:
// Main is a thread also and it will sleep 2 seconds now.
// Main thread woke up.
void BlackLib::BlackThread::stop ( )

Stops thread execution.

This function stops and exits the thread function. After users call this function, thread starts the BlackThread::cleanUp() function. This clean up function runs the onStopHandler() function in users derived class, after some final processes.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
if( t1->isRunning() )
{
t1->stop();
}
return 0;
}
See also
cleanUp()
onStopHandler()
void * BlackLib::BlackThread::threadFunction ( void *  thread)
staticprivate

Thread's main function.

This function is the main function of thread. The thread runs this function actually. It does some preparation operations like setting up the cleanup system. After that it runs onStartHandler() function and waits until it finished. Then the cleanup system is put into use.

This function's mission is to do some background job and users should not call this function directly.

See also
onStartHandler()
void BlackLib::BlackThread::usleep ( unsigned int  usec)
static

Sleeps the thread for specified microsecond(s).

Parameters
[in]usectime in microseconds
Example
std::cout << "Main is a thread also and it will sleep 2000 microseconds now." << std::endl;
std::cout << "Main thread woke up." << std::endl;
// Possible Output:
// Main is a thread also and it will sleep 2000 microseconds now.
// Main thread woke up.
void BlackLib::BlackThread::waitUntilFinish ( )

Waits thread until it finished.

This function joins the thread if thread's state is "running" or "paused". This means the program will wait here until the thread function (in other words onStartHandler function) finishes. This function should use before the last line of main code (before "return 0;" line at the main.cpp). Users can use WAIT_THREAD_FINISH() macro also. It is the same thing. If users don't use this function or macro and the program comes to last line of main, the program will exit and thread will be interrupted. This cause some fatal things.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
if( t1->isRunning() )
{
t1->stop();
}
return 0;
}
void BlackLib::BlackThread::yield ( )
static

Yields thread.

Yields execution of the current thread to another thread.

Example
class Task1 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
class Task2 : public BlackLib::BlackThread
{
public:
{
// do something here
}
{
// do something here
}
};
int main()
{
Task1 *t1 = new Task1();
Task2 *t2 = new Task2();
t1->run();
t2->run();
t1->yield();
return 0;
}

Member Data Documentation

bool BlackLib::BlackThread::isCreated
private

is used to hold the thread is created or not

pthread_t BlackLib::BlackThread::nativeThread
private

is used to hold the thread's posix id

std::vector<int> BlackLib::BlackThread::priorities
private

is used to hold the OS based calculated priority values

BlackThread::priority BlackLib::BlackThread::threadPriority
private

is used to hold the thread priority

BlackThread::state BlackLib::BlackThread::threadState
private

is used to hold the thread state


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