 |
You.i Engine
|
|
|
You.i Engine
|
|
A CYIFuture object is a container for a value that will be assigned at a future time, typically from a different thread. The templated type of this class is the type of value that can be stored in this object.
Functions are provided to allow a user to get the result of the content of the CYIFuture. If no value has been assigned yet, the user's thread will block until a value is assigned, or until a user-specified timeout is reached. Once a value has been assigned, the getter functions return immediately.
A value can only be assigned to a CYIFuture once. Further attempts to assign a value will return failure and will have no effect.
When used with pointer types, CYIFuture objects takes ownership of pointers assigned to them. When the future is deleted, the contained object is deleted as well. This can be prevented by calling Take() to take ownership of the contained object.
Signals can optionally be connected so that users are notified when a value is assigned to the CYIFuture. When used with an associated CYITask, additionnal signals are available to notify when the task's execution has started or when the task has been cancelled.
A CYIFuture object can optionally be associated with a CYITask object. This association is done through the CYITask itself. Only one task can be associated with a CYIFuture object, and that link cannot be broken once it has been made. When used with an associated task, cancelling a future will result in the associated task being cancelled as well (unless it has already started executing). Deleting a CYIFuture object will automatically result in an associated task to be cancelled.
All public functions, with the exception of the destructor, are thread-safe.
| ResultType | the type of object that can be assigned to this Future object. |
#include <thread/YiFuture.h>
Public Member Functions | |
| CYIFuture () | |
| virtual | ~CYIFuture () |
| bool | Get (ResultType *pValue) const |
| const ResultType & | Get () const |
| bool | Get (ResultType *pValue, uint32_t uTimeoutMs) const |
| const ResultType & | Get (uint32_t uTimeoutMs) const |
| bool | Set (const ResultType &rValue) |
 Public Member Functions inherited from CYIAbstractFuture | |
| virtual | ~CYIAbstractFuture () |
| bool | IsCancelled () const |
| bool | IsCompleted () const |
| bool | Cancel () |
| bool | CancelOrWait () |
| bool | Wait () const |
| bool | Wait (uint64_t uTimeoutMs) const |
Public Attributes | |
| CYISignal< const ResultType & > | Completed |
| A signal triggered when a value is assigned to this object. More... | |
| Public Attributes inherited from CYIAbstractFuture | |
| CYISignal | ExecutionStarted |
| A signal triggered when an associated task begins execution. More... | |
| CYISignal | Cancelled |
| A signal triggered when this object is cancelled. More... | |
Protected Member Functions | |
| bool | SetCompleted (const ResultType &rValue) |
| Equivalent to CYIFuture<ResultType>::Set(), but requires that m_mutex be locked prior to calling this function. More... | |
| Protected Member Functions inherited from CYIAbstractFuture | |
| void | ExclusiveLock () const |
| Locks both this object and the associated task (if it exists). More... | |
| void | ExclusiveUnlock () const |
| Unlocks both this object and the associated task (if it exists). More... | |
| void | NotifyStateChanged () const |
| Notify waiters (e.g. threads blocked on calls to Wait, Get or Take) of state change. More... | |
| bool | SetTask (CYITaskBase *pTask) |
| Sets the task asssociated with this object to the provided task. Returns true if the task was associated successfully, false otherwise. Has no effect if a task has already been assigned, or if this future has been cancelled or had a value assigned already. More... | |
| void | DisconnectFromTask () |
| Removes the task reference, if it exists. If an associated task exists, an attempt is made at cancelling it. More... | |
| bool | SetCancelledNonLocking () |
| Sets the 'cancelled' flag on this object, if it hasn't been done already and the future hasn't had a value assigned to it. Will awaken all waiters if the cancellation was successful (and will trigger the Cancelled signal). Returns false if the future could not be cancelled. The caller must have m_mutex locked. More... | |
| bool | WaitNonLocking () const |
| Equivalent to the Wait() function, but the caller must have m_mutex locked. More... | |
| bool | WaitNonLocking (uint64_t uTimeoutMs) const |
| Equivalent to the Wait() function, but the caller must have m_mutex locked. More... | |
| bool | CancelInternal (bool bWait) |
Friends | |
| template<typename T > | |
| class | CYITask |
| bool CYIFuture< ResultType >::Get | ( | ResultType * | pValue | ) | const |
Waits until a value has been assigned to this object, or until this object has been cancelled. If a value has been assigned, the value is copied into the provided variable. If the future is cancelled, the specified variable is untouched.
| const ResultType& CYIFuture< ResultType >::Get | ( | ) | const |
Waits until a value has been assigned to this object, or until this object has been cancelled. If a value has been assigned, a reference to the value is returned. If the future is cancelled, a value constructed by the default constructor of ResultType is returned.
| bool CYIFuture< ResultType >::Get | ( | ResultType * | pValue, |
| uint32_t | uTimeoutMs | ||
| ) | const |
Waits until a value has been assigned to this object, until this object has been cancelled, or until the specified timeout is reached. If a value has been assigned, a copy of the value is stored in the provided variable. If the future is cancelled or if the timeout value is reached, the provided variable is untouched.
| const ResultType& CYIFuture< ResultType >::Get | ( | uint32_t | uTimeoutMs | ) | const |
Waits until a value has been assigned to this object, until this object has been cancelled, or until the specified timeout is reached. If a value has been assigned, a reference to it is returned. If the future is cancelled or if the timeout value is reached, a value constructed by the default constructor of ResultType is returned.
| bool CYIFuture< ResultType >::Set | ( | const ResultType & | rValue | ) |
Assigns a value to this object.
A value can only be assigned once, and cannot be done if the future has been cancelled. A successful assignment will result in the Completed signal being triggered as well as threads blocked on calls to Wait and Get to wake up.
|
protected |
Equivalent to CYIFuture<ResultType>::Set(), but requires that m_mutex be locked prior to calling this function.
| CYISignal<const ResultType&> CYIFuture< ResultType >::Completed |
A signal triggered when a value is assigned to this object.
1.8.11