task_builder dispatch

nes::task_builder::dispatch

Functions

    template<typename Func, typename... Args>
(1) void dispatch(std::uint32_t x, std::uint32_t y, std::uint32_t z, Func&& func, Args&&... args);

1. Pushes one or more tasks in the task list. The function will be called for a total of x * y * z calls, each of them will get a unique combination of x, y, and z. This function will generate at most thread_count tasks, each one will call the function (x * y * z) / thread_count, and (x * y * z) % thread_count tasks will call the function one more time. The total amount of calls (x * y * z) must not be greater than 2^64 - 1 (18 446 744 073 709 551 615).

The function is guaranteed to be called with a specific pattern of x, y and z: after each call x will be incremented, when it hits the x limit, it will increment y and set x to 0. Same goes for y and z, when y hits the y limit, it will increment z and set y to 0. This may be used to optimize cached accesses of linear arrays.
Example for x == 2, y == 2, x == 2 and thread_count == 1, the calls will be ordered as follows within a single task:

Call	x	y	z
0	0	0	0
1	1	0	0
2	0	1	0
3	1	1	0
4	0	0	1
5	1	0	1
6	0	1	1
7	1	1	1

The function will be called as-if by calling std::invoke(func, x, y, z, args...);. The return value of the function, if any, will be discarded. The arguments to the function are copied by value, if a reference argument needs to be passed, it has to be wrapped using std::[c]ref, or any other wrapper.

Parameters

Name	Description
func	The function to be executed.
x	The number of invocation in x-dimension.
y	The number of invocation in y-dimension.
z	The number of invocation in z-dimension.
args	The arguments to be passed to func.

Return value

None.

Preconditions

1. func must be copyable, and std::invoke(func, x, y, z, args...); must be well-formed.

Exceptions

May throw a std::bad_alloc.