You.i Engine
Threading

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:

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

#define YI_LOCKLESS_CACHE_SIZE   3

Function Documentation

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.

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

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

const int32_t YI_MAX_THREADS = 100