#include <jobgroup.h>
Detailed Description
Heterogenous job group. The jobs can be of different type and you can add them to the group until you enqueue it (or while the group is running when you use AddSubJob). A job group is free to remove the reference to its jobs or subgroups once they are executed. Creating a job group and jobs is very fast and therefore there's no need to prebuild and perhaps even cache them.
Private Member Functions | |
| JobGroupInterface () | |
| ~JobGroupInterface () | |
Friends | |
| class | StrongRefHandler |
| class | CoreJobGroup |
| template<typename > | |
| struct | ObservableFinishedBase |
Constructor & Destructor Documentation
◆ JobGroupInterface()
|
private |
◆ ~JobGroupInterface()
|
private |
Member Function Documentation
◆ Enqueue()
| JobGroupInterface* Enqueue | ( | JobQueueInterface * | queue = JOBQUEUE_CURRENT | ) |
Enqueues all jobs of the group including subgroups (will add a reference and remove it when the object is no longer needed). Please note that a group (like a job) can only be enqueued once. THREADSAFE.
- Parameters
-
[in] queue The queue, use JOBQUEUE_CURRENT for the current queue.
- Returns
- Always this (for concatenation).
◆ EnqueueAndWait()
| Result<void> EnqueueAndWait | ( | JobQueueInterface * | queue = JOBQUEUE_CURRENT | ) |
Enqueues all jobs of the group including subgroups and waits for them. This implicitely indicates to the system that the current job cannot continue until the group has finished. THREADSAFE.
- Parameters
-
[in] queue The queue, use JOBQUEUE_CURRENT for the current queue.
- Returns
- OK on success.
◆ Wait()
| Bool Wait | ( | TimeValue | timeout = TIMEVALUE_INFINITE, |
| WAITMODE | mode = WAITMODE::DEFAULT |
||
| ) | const |
Waits until all jobs of the group have been executed.
Wait() might execute other jobs in the current queue until the group you are waiting for has finished or is timed out. Therefore you may never lock a shared resource another job might use as well and then wait. For one this could dead-lock and conceptually this would result in single-threaded performance.
If you try to call Wait() from a job which did not enqueue the group it will immediately return false because this would lead to a deadlock.
Instead of waiting for some group to start some action after it has finished you can subscribe to ObservableFinished(). This cannot dead-lock, is more efficient and can even be used to run the observer in a different queue. For example you can run a job and register an observer for it that will run on the main thread's queue and updates the UI. THREADSAFE.
- Parameters
-
[in] timeout Maximum wait interval (or TIMEVALUE_INFINITE for no time-out). [in] mode WAITMODE::DEFAULT by default. WAITMODE::RETURN_ON_CANCEL means that Wait() will return if the caller has been cancelled even if the condition has not been set yet.
- Returns
- True if successful, false if you try to wait inside an enqueued job.
◆ GetResult()
| Result<void> GetResult | ( | TimeValue | timeout = TIMEVALUE_INFINITE, |
| WAITMODE | mode = WAITMODE::DEFAULT |
||
| ) | const |
Waits until the group has been executed and returns OK on success or any errors returned by its jobs. If there are errors this might return an AggregatedError. THREADSAFE.
- Parameters
-
[in] timeout Maximum wait interval (or TIMEVALUE_INFINITE for no time-out). [in] mode WAITMODE::DEFAULT by default. WAITMODE::RETURN_ON_CANCEL means that Wait() will return if the caller has been cancelled even if the condition has not been set yet.
- Returns
- OK on success.
◆ Add() [1/6]
| Result<void> Add | ( | JobInterface * | job | ) |
Adds a job to the group. The group takes exclusive ownership of the job. The job will be deleted after it has been executed, when the group will be deleted or when adding the job fails. The job must have been created using DefaultAllocator, e.g. with Create() or NewObj(). If you had created a job on the stack or used a custom allocator this would lead to a crash. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] job Job (nullptr will return error).
- Returns
- OK on success.
◆ Add() [2/6]
Adds a job to the group. The group takes exclusive ownership of the job. The job will be deleted after it has been executed, when the group will be deleted or when adding the job fails. The job must have been created using DefaultAllocator, e.g. with Create() or NewObj(). If you had created a job on the stack or used a custom allocator this would lead to a crash. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] job Job (nullptr will return error).
- Returns
- OK on success.
◆ Add() [3/6]
| Result<void> Add | ( | ResultMemT< T * > | job | ) |
Adds a job to the group. The group takes exclusive ownership of the job. The job will be deleted after it has been executed, when the group will be deleted or when adding the job fails. The job must have been created using DefaultAllocator, e.g. with Create() or NewObj(). If you had created a job on the stack or used a custom allocator this would lead to a crash. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] job Job (encapsulated in a ResultMemT directly returned from creation).
- Returns
- OK on success.
◆ Add() [4/6]
| Result<void> Add | ( | ResultMemT< JOBREF > && | job | ) |
Adds a job to the group. The group takes exclusive ownership of the job. The job will be deleted after it has been executed, when the group will be deleted or when adding the job fails. The job must have been created using DefaultAllocator, e.g. with Create() or NewObj(). If you had created a job on the stack or used a custom allocator this would lead to a crash. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] job Job (encapsulated in a ResultMemT directly returned from creation).
- Returns
- OK on success.
◆ DISABLE_IF_JOB_OR_GROUP()
| DISABLE_IF_JOB_OR_GROUP | ( | FN | , |
| Result< void > | |||
| ) | && |
Encapsulates a lambda or object with operator () in a JobInterface and adds this job to the group. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] src Lambda or object with operator ().
- Template Parameters
-
B Behaviour for early job cancellation. FN Type of function/lambda, deduced by the compiler.
- Returns
- OK on success.
◆ Add() [5/6]
Adds an array with multiple jobs of the same type to the group (faster than single Add()s). The group takes exclusive ownership of the jobs. The jobs and the memory for the array will be freed after they have been executed. If adding the jobs failed they and the memory will be deleted automatically. The array must use the DefaultAllocator for memory allocations. Do not use a custom allocator because this would lead to a crash. As long as the group is not enqueued you can add jobs from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further jobs. THREADSAFE.
- Parameters
-
[in] jobs A BaseArray containing your jobs.
- Returns
- OK on success.
◆ Add() [6/6]
| Result<void> Add | ( | JobGroupInterface * | subGroup | ) |
Adds a subgroup to the group. This will add a reference to the group and remove it when the group is not accessed anymore. If adding a subgroup fails its reference will be removed and its jobs will be stopped. As long as the group is not enqueued you can add subgroups from any thread. As soon as it is enqueued only jobs belonging to the group are allowed to add further subgroups. THREADSAFE.
- Parameters
-
[in] subGroup Group object (nullptr will return error).
- Returns
- OK on success.
◆ ObservableFinished()
| ObservableFinishedBase<JobGroupInterface> ObservableFinished | ( | ) |
ObservableFinished is an observable that is triggered after this group has been executed. THREADSAFE.
- Returns
- Custom observable.
◆ Cancel()
| void Cancel | ( | ) |
Asks the group to cancel execution of all jobs that are enqueued. Currently running jobs are not affected unless they call IsCancelled(). If this is a subgroup the parent group will be cancelled too. The call will not wait for the group to cancel and it can be called from any thread or job. THREADSAFE.
◆ CancelAndWait()
| void CancelAndWait | ( | WAITMODE | mode = WAITMODE::DEFAULT | ) |
Asks the group to cancel execution and waits until it has finished. THREADSAFE.
- Parameters
-
[in] mode WAITMODE::DEFAULT by default.
◆ ToString()
| String ToString | ( | const FormatStatement * | formatStatement = nullptr | ) | const |
Returns a readable string of the content.
- Parameters
-
[in] formatStatement Nullptr or additional formatting instruction. Currently no additional formatting instructions are supported.
- Returns
- The converted result.
Friends And Related Function Documentation
◆ StrongRefHandler
|
friend |
◆ CoreJobGroup
|
friend |
◆ ObservableFinishedBase
|
friend |