Detailed Description

Thread and synchronization classes.

These classes are provided to implement and manipulate threads. Data structures are also provided to communicate and share resources between threads.

Threading Model in You.i Engine

Most code in apps using You.i Engine execute on what is called the Main Thread (or Event Thread). Any access and manipulation to the scene tree must be made from the Main Thread. When code is running on a different thread and needs to access or manipulate things from the Main Thread, one of the following can be done:

Use a CYISignal. Signals that have been connected from the Main Thread, when executed, will automatically switch thread context to call the Slot on the Main Thread instead. Signals and Slots
Use a CYITask queued for execution using the CYIThreadPools::RunOnUIThread() function.

You.i Engine Thread Object

The CYIThread class is used to represent an execution thread. Users can create instances of this class (which must first be subclassed and have their CYIThread::Run() method implemented) in order to start executing code concurrently.

Each thread is identified by a CYIThreadHandle object. While the Main Thread doesn't have an associated CYIThread object, it does have a CYIThreadHandle object which is accessible through the CYIThread::GetCurrentThreadId() function. To access the thread handle of the main thread, the CYIThread::GetCurrentThreadId() function must be called from the Main Thread itself.

Thread Pools

Thread pools manage a collection of CYIThread objects, which execute queued CYITask objects. The result of the execution of these tasks is available through CYIFuture objects.

Two classes are used to manage thread pools. The CYIThreadPool class is the container that holds and manages a collection of CYIThread objects. The CYIThreadPools class provides a default system thread pool, initialized to hold as many hot-standby threads as execution units are available on the user's system. The CYIThreadPools class also provides convenience functions to execute one-off tasks, and to execute tasks on the Main Thread.

Thread Manager

Unlike thread pools, thread managers (implemented by CYIThreadManager) do not create CYIThread objects or hold references to them. Instead, they act as a permission mechanism to tell users when they can create more threads. This is to avoid creating so many threads that the user's system gets slowed down.

Synchronization

When multiple threads may be accessing the resource (e.g. accessing the same variable), the access to that resource must be managed to ensure that only one thread is accessing it at a time. This is typically done using std::mutex objects (or the helper class std::lock_guard). Other types of mutexes exist with different capabilities: std::recursive_mutex, CYIReadWriteMutex and CYISpinLock. The latter isn't a subclass of std::mutex, but its purpose is similar.

Instead of using mutexes to protect data, special thread-safe data types can also be used. The std::atomic class provides a thread-safe data type that guarantees that only one thread can read or write to it at a time.

When the ordering of execution between thread needs to be managed (e.g. to ensure that Thread 1 only continues executing until a condition is set by Thread 2), synchronization objects can be used. The most common is std::condition_variable, which allows a thread to wait (or 'block') until a specific condition is met. The CYICountDownLatch class can also be used as a simple notification mechanism between threads.

Namespaces
	yi::deprecated
	Deprecated classes.

Classes
class	CYIAutoReadMutex

class	CYIAutoWriteMutex

class	CYICallableTask< ResultType, Callable, Args >
	An utility class used to create a task from a callable object. More...

class	CYICountDownLatch

class	CYIEventDispatcherThread

class	CYIAbstractFuture

class	CYIFuture< ResultType >

class	CYIFuture< void >

class	CYIFuture< ResultType * >

class	CYIFuture< ResultType[]>

class	CYILocklessCache< YI_CACHE_TYPE >
	Lockless cache is a triple-buffered cache. More...

class	CYIReadWriteMutex

class	CYIRecursiveSpinLock
	Provides access serialization between threads, where a thread trying to acquire the lock waits in a loop repeatedly checking until the lock becomes available. More...

class	CYISpinLock
	Provides access serialization between threads, where a thread trying to acquire the lock waits in a loop repeatedly checking until the lock becomes available. More...

class	CYIStaticTask< ResultType >
	An utility class used to create a task from a static function. More...

class	CYITaskBase

class	CYITask< ResultType >

class	CYITask<>

class	CYITask< ResultType * >

class	CYITask< ResultType[]>

class	CYIThread

class	CYIThreadHandle

class	CYIThreadPool

class	CYIThreadPools

Macros
#define	YI_LOCKLESS_CACHE_SIZE 3

Functions
template<typename Callable , typename... Args>
auto	YiMakeTask (Callable callable, Args &&... args) -> std::unique_ptr< CYICallableTask< decltype(callable(std::move(args)...)), Callable, Args... >>

template<typename ResultType , typename Callable , typename... Args>
auto	YiMakeTask (CYIFuture< ResultType > future, Callable callable, Args &&... args) -> std::unique_ptr< CYICallableTask< decltype(callable(std::move(args)...)), Callable, Args... >>

Variables
const int32_t	YI_MAX_THREADS = 100

Macro Definition Documentation

◆ YI_LOCKLESS_CACHE_SIZE

#define YI_LOCKLESS_CACHE_SIZE 3

Function Documentation

◆ YiMakeTask() [1/2]

template<typename Callable , typename... Args>

auto YiMakeTask	(	Callable	callable,
		Args &&...	args
	)		-> std::unique_ptr< CYICallableTask< decltype(callable(std::move(args)...)), Callable, Args... >>

inline

Returns a std::unique_ptr containing a new instance of CYICallableTask from the callable object callable and the optional arguments args. No future object is associated with the returned task.

Note: This variant passes the task to the Callable as first parameter when the task is executed. This allows the Callable to detect and respond to cancellation requests.

◆ YiMakeTask() [2/2]

template<typename ResultType , typename Callable , typename... Args>

auto YiMakeTask	(	CYIFuture< ResultType >	future,
		Callable	callable,
		Args &&...	args
	)		-> std::unique_ptr< CYICallableTask< decltype(callable(std::move(args)...)), Callable, Args... >>

inline

Returns a std::unique_ptr containing a new instance of CYICallableTask from the callable object callable and the optional arguments args. The future future is associated with the task.

Note: This variant passes the task to the Callable as first parameter when the task is executed. This allows the Callable to detect and respond to cancellation requests.

Variable Documentation

◆ YI_MAX_THREADS

const int32_t YI_MAX_THREADS = 100