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:

[legend]

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 CYIString &	GetName () 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 CYIThreadHandle &	GetUIThreadId ()

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

◆ Priority

enum CYIThread::Priority

strong

Enumerator
Minimum
Low
Normal
High
Maximum
Inherited
Default

◆ StartType

enum CYIThread::StartType

strong

Enumerator
NonBlocking
BlockUntilStarted

Constructor & Destructor Documentation

◆ CYIThread()

CYIThread::CYIThread	(	const CYIString &	name = `CYIString()`,
		Priority	priority = `Priority::Default`,
		size_t	stackSize = `DEFAULT_STACK_SIZE`
	)

◆ ~CYIThread()

virtual CYIThread::~CYIThread ( )

virtual

Blocking until the thread terminates.

Calls Join() before cleaning up the thread.

Member Function Documentation

◆ AddThreadListener()

bool CYIThread::AddThreadListener ( Listener * pListener )

Register a CYIThreadListener to monitor this thread.

Note: This function is thread-safe.

◆ DisableTermination()

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()

◆ EnableTermination()

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()

◆ GetCurrentThreadId()

static CYIThreadHandle CYIThread::GetCurrentThreadId ( )

static

Returns the CYIThreadHandle of the caller's current context.

◆ GetName()

const CYIString& CYIThread::GetName ( ) const

Gets the name of the thread

Note: This function is thread-safe.

◆ GetPriority()

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.

◆ GetStackSize()

size_t CYIThread::GetStackSize ( ) const

Returns the thread stack size.

Note: This function is thread-safe.

◆ GetThreadId()

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().

◆ GetUIThreadId()

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

◆ IsRunning()

bool CYIThread::IsRunning ( ) const

Checks if the thread is running.

Note: This function is thread-safe.

◆ IsTerminationEnabled()

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()

◆ 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()

◆ Join() [1/2]

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.

◆ Join() [2/2]

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.

◆ RemoveThreadListener()

bool CYIThread::RemoveThreadListener ( Listener * pListener )

Unregister a CYIThreadListener.

Note: This function is thread-safe.

◆ ReportDefaults()

static void CYIThread::ReportDefaults ( )

static

Prints a thread report based on default thread settings.

◆ Run()

virtual void CYIThread::Run ( )

protectedpure virtual

Implemented in CYIEventDispatcherThread.

◆ SetName()

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.

◆ SetPriority()

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.

◆ SetStackSize()

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.

◆ Sleep()

static void CYIThread::Sleep ( uint32_t millis )

static

Sleep function. Time unit is in millisecond.

Wraps the YI_SLEEP macro.

◆ StartThread()

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.

◆ Terminate()

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()

◆ YieldCurrentThread()

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

◆ CYIThreadPriv

friend class CYIThreadPriv

friend

Member Data Documentation

◆ DEFAULT_STACK_SIZE

const size_t CYIThread::DEFAULT_STACK_SIZE = 128 * 1024

static

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

thread/YiThread.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Member Enumeration Documentation

◆ Priority

◆ StartType

Constructor & Destructor Documentation

◆ CYIThread()

◆ ~CYIThread()

Member Function Documentation

◆ AddThreadListener()

◆ DisableTermination()

◆ EnableTermination()

◆ GetCurrentThreadId()

◆ GetName()

◆ GetPriority()

◆ GetStackSize()

◆ GetThreadId()

◆ GetUIThreadId()

◆ IsRunning()

◆ IsTerminationEnabled()

◆ IsTerminationRequested()

◆ Join() [1/2]

◆ Join() [2/2]

◆ RemoveThreadListener()

◆ ReportDefaults()

◆ Run()

◆ SetName()

◆ SetPriority()

◆ SetStackSize()

◆ Sleep()

◆ StartThread()

◆ Terminate()

◆ YieldCurrentThread()

Friends And Related Function Documentation

◆ CYIThreadPriv

Member Data Documentation

◆ DEFAULT_STACK_SIZE