You.i Engine
CYIThread Class Referenceabstract

Detailed Description

This class provides the required mechanism to manage and control threads.

The main way to use CYIThread is to make a subclass, and implmement the CYIThread::Run() and CYIThread::CleanUp() function. The CYIThread::Run() is executed by the new thread after CYIThread::StartThread() has been called. CYIThread::CleanUp() is called as soon as Run() exits. CYIThread::CleanUp will also be called if the user forcefully terminates the thread by calling CYIThread::Terminate().

Warning
Before an instance of CYIThread can be deleted, a Join() function must be called on the instance. Failure to call a Join() function prior to deleting the CYIThread instance will result in an error being logged and the program crashing. To ensure that Join() is called prior to deleting, it is highly recommended that the function CYIThread::Join() be called from the sub-class' destructor.
class MyThread : public CYIThread
{
private:
MyWorker *m_pWorker;
protected:
virtual void Run()
{
printf("Called by the new thread after CYIThread::StartThread() has been called.\n");
bool continue;
do
{
continue = m_pWorker->DoWork();
}
while (continue);
}
virtual void Terminate() // overriden, to gracefully break the loop in Run()
{
m_pWorker->StopWorkingNow();
}
};
std::unique_ptr<MyThread> pThread;
void Setup()
{
pThread = std::make_unique<MyThread>();
pThread->StartThread();
pThread->Join();
pThread.reset();
}

#include <thread/YiThread.h>

Inheritance diagram for CYIThread:

Classes

class  Listener
 

Public Types

enum  Priority {
  Priority::Minimum = 0,
  Priority::Low,
  Priority::Normal,
  Priority::High,
  Priority::Maximum,
  Priority::Inherited,
  Priority::Default = Inherited
}
 
enum  StartType {
  StartType::NonBlocking = 0,
  StartType::BlockUntilStarted = 1
}
 

Public Member Functions

 CYIThread (const CYIString &name=CYIString(), Priority priority=Priority::Default, size_t stackSize=DEFAULT_STACK_SIZE)
 
virtual ~CYIThread ()
 
bool StartThread (StartType startType=StartType::BlockUntilStarted)
 
void Terminate ()
 
void EnableTermination ()
 
void DisableTermination ()
 
bool IsTerminationEnabled ()
 
bool Join ()
 
bool Join (uint32_t timeoutMs)
 
bool IsRunning () const
 
CYIThreadHandle GetThreadId () const
 
void SetName (const CYIString &name)
 
const CYIStringGetName () const
 
void SetPriority (Priority priority)
 
Priority GetPriority () const
 
bool AddThreadListener (Listener *pListener)
 
bool RemoveThreadListener (Listener *pListener)
 
bool SetStackSize (size_t stackSize)
 
size_t GetStackSize () const
 

Static Public Member Functions

static CYIThreadHandle GetCurrentThreadId ()
 
static const CYIThreadHandleGetUIThreadId ()
 
static int32_t GetOSIdealThreadCount ()
 
static void Sleep (uint32_t millis)
 
static void YieldCurrentThread ()
 
static void ReportDefaults ()
 

Static Public Attributes

static const size_t DEFAULT_STACK_SIZE = 128 * 1024
 

Protected Member Functions

virtual void Run ()=0
 
bool IsTerminationRequested () const
 

Friends

class CYIThreadPriv
 

Member Enumeration Documentation

enum CYIThread::Priority
strong
Enumerator
Minimum 
Low 
Normal 
High 
Maximum 
Inherited 
Default 
enum CYIThread::StartType
strong
Enumerator
NonBlocking 
BlockUntilStarted 

Constructor & Destructor Documentation

CYIThread::CYIThread ( const CYIString name = CYIString(),
Priority  priority = Priority::Default,
size_t  stackSize = DEFAULT_STACK_SIZE 
)
virtual CYIThread::~CYIThread ( )
virtual

Blocking until the thread terminates.

Calls Join() before cleaning up the thread.

Member Function Documentation

bool CYIThread::AddThreadListener ( Listener pListener)

Register a CYIThreadListener to monitor this thread.

Note
This function is thread-safe.
void CYIThread::DisableTermination ( )

Manually disables the thread termination feature. Calling Terminate() will have no effect.

Note
This function is thread-safe.
Warning
Terminate() won't terminate a thread if the user re-implemented it.
See also
Terminate()
DisableTermination()
IsTerminationEnabled()
void CYIThread::EnableTermination ( )

Manually enables the thread termination feature. Calling Terminate() will terminate the thread's execution if thread termination is supported on the platform.

Thread termination is enabled by default on platforms which support thread termination. This function will assert on platforms which do not support thread termination.

Note
This function is thread-safe.
Warning
Terminate() won't terminate a thread if the user re-implemented it.
See also
Terminate()
DisableTermination()
IsTerminationEnabled()
static CYIThreadHandle CYIThread::GetCurrentThreadId ( )
static

Returns the CYIThreadHandle of the caller's current context.

const CYIString& CYIThread::GetName ( ) const

Gets the name of the thread

Note
This function is thread-safe.
static int32_t CYIThread::GetOSIdealThreadCount ( )
static

Gets the ideal thread count. The amount is provided by the operating system and will vary between platforms.

Priority CYIThread::GetPriority ( ) const

Gets the priority of the thread

Warning
Might not match the real priority of the running thread if CYIThread::SetPriority(YI_PRIORITY priority) was called after calling CYIThread::StartThread().
Note
This function is thread-safe.
size_t CYIThread::GetStackSize ( ) const

Returns the thread stack size.

Note
This function is thread-safe.
CYIThreadHandle CYIThread::GetThreadId ( ) const

Gets the thread handle of the thread. Will print a warning if the thread is not running.

Warning
The CYIThreadHandle will be invalid if the thread is not running. Make sure you check the tread running state using CYIThread::IsRunning() before calling CYIThread::GetThreadId().
static const CYIThreadHandle& CYIThread::GetUIThreadId ( )
static

Returns the CYIThreadHandle of You.i Engine's UI thread.

Note
The returned thread handle will only be valid after application initializtion is complete.
See also
CYIApp::Init
bool CYIThread::IsRunning ( ) const

Checks if the thread is running.

Note
This function is thread-safe.
bool CYIThread::IsTerminationEnabled ( )

Checks if the termination feature is turned on or off. If this function returns false, it means that Terminate() won't have any effect other than requesting termination.

Note
Thread termination is always disabled on platforms which do not support thread termination.
See also
IsTerminationRequested()
bool CYIThread::IsTerminationRequested ( ) const
protected

This function immediately returns true after Terminate() has been invoked.

By default, calling Terminate() aborts the thread execution (if thread termination is supported on the platform). The user can chose to disable thread termination by invoking DisableTermination(), and then poll IsTerminationRequested on regular intervals by the thread's code (Run()) to check if the thread was requested to terminate.

Note
This function is thread-safe.
See also
Terminate()
EnableTermination()
DisableTermination()
bool CYIThread::Join ( )

Waits for the thread to terminate.

Note
This function is thread-safe.
Returns
Returns true if the thread is no longer running.
bool CYIThread::Join ( uint32_t  timeoutMs)

Waits for the thread to terminate with a time limit.

Note
This function may return before timeoutMs is reached even if the thread hasn't completed yet due to spurious wake-ups. Always check the return value to see if the thread has completed.
This function is thread-safe.
Returns
Returns true if the thread is no longer running.
bool CYIThread::RemoveThreadListener ( Listener pListener)

Unregister a CYIThreadListener.

Note
This function is thread-safe.
static void CYIThread::ReportDefaults ( )
static

Prints a thread report based on default thread settings.

virtual void CYIThread::Run ( )
protectedpure virtual

Implemented in CYIEventDispatcherThread.

void CYIThread::SetName ( const CYIString name)

Changes the name of the thread. Can also be changed while the thread is running. Very useful for debugging.

Note
On some platforms (e.g. OSX and iOS), the name can only be set prior to starting the thread.
This function is thread-safe.
void CYIThread::SetPriority ( Priority  priority)

Changes the priority of the thread. Can also be changed while the thread is running.

Note
This function is thread-safe.
bool CYIThread::SetStackSize ( size_t  stackSize)

Changes the stack size of the thread.

Warning
Must be called before CYIThread::StartThread() is called. Otherwise it won't have any effect.
Note
This function is thread-safe.
static void CYIThread::Sleep ( uint32_t  millis)
static

Sleep function. Time unit is in millisecond.

Wraps the YI_SLEEP macro.

bool CYIThread::StartThread ( StartType  startType = StartType::BlockUntilStarted)

Creates a new thread, causes Run() to be called from there. This function returns immediately, Run() is called asynchronously This function returns true if the thread started successfully.

By default

Note
This function is thread-safe.
void CYIThread::Terminate ( )

Asynchronously aborts the thread's execution if thread termination is enabled. Returns immediately without waiting for the actual termination. The user needs to wait for the thread to terminate, it can be done by either call Join(), or listening for the Terminated signal, or register for the event OnThreadTerminated by implementing the listener class above.

After calling this function, IsTerminationRequested() will return true.

Warning
This function can be very dangerous and its use is highly discouraged. This can potentially create memory leaks and/or not release resources such locked mutexex since the thread has no way to clean after itself. Use at your own risk. If you are allocating/acquiring any type resources in your Run() function, you can also invoke DisableTermination(), and poll IsTerminationRequested() from your Run() function to detect if the user invoked Terminate().
Note
This function is thread-safe.
See also
EnableTermination()
DisableTermination()
IsTerminationEnabled()
static void CYIThread::YieldCurrentThread ( )
static

Request to yield execution to another thread that is ready to run on the current processor.

Friends And Related Function Documentation

friend class CYIThreadPriv
friend

Member Data Documentation

const size_t CYIThread::DEFAULT_STACK_SIZE = 128 * 1024
static

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