Parallelism

Most modern microprocessors consist of more than one core, each of which can operate as an individual processing unit. They can execute different parts of different programs at the same time. The features of the std.parallelism module make it possible for programs to take advantage of all of the cores in order to run faster.

This chapter covers the following range algorithms. These algorithms should be used only when the operations that are to be executed in parallel are truly independent from each other. In parallel means that operations are executed on multiple cores at the same time:

parallel : Accesses the elements of a range in parallel.

: Accesses the elements of a range in parallel. task : Creates tasks that are executed in parallel.

: Creates tasks that are executed in parallel. asyncBuf : Iterates the elements of an InputRange semi-eagerly in parallel.

: Iterates the elements of an semi-eagerly in parallel. map : Calls functions with the elements of an InputRange semi-eagerly in parallel.

: Calls functions with the elements of an semi-eagerly in parallel. amap : Calls functions with the elements of a RandomAccessRange fully-eagerly in parallel.

: Calls functions with the elements of a fully-eagerly in parallel. reduce : Makes calculations over the elements of a RandomAccessRange in parallel.

In the programs that we have written so far we have been assuming that the expressions of a program are executed in a certain order, at least in general line-by-line:

++i; ++j;

In the code above, we expect that the value of i is incremented before the value of j is incremented. Although that is semantically correct, it is rarely the case in reality: microprocessors and compilers use optimization techniques to have some variables reside in microprocessor's registers that are independent from each other. When that is the case, the microprocessor would execute operations like the increments above in parallel.

Although these optimizations are effective, they cannot be applied automatically to layers higher than the very low-level operations. Only the programmer can determine that certain high-level operations are independent and that they can be executed in parallel.

In a loop, the elements of a range are normally processed one after the other, operations of each element following the operations of previous elements:

auto students = [ Student(1), Student(2), Student(3), Student(4) ]; foreach (student; students) { student.aSlowOperation(); }

Normally, a program would be executed on one of the cores of the microprocessor, which has been assigned by the operating system to execute the program. As the foreach loop normally operates on elements one after the other, aSlowOperation() would be called for each student sequentially. However, in many cases it is not necessary for the operations of preceding students to be completed before starting the operations of successive students. If the operations on the Student objects were truly independent, it would be wasteful to ignore the other microprocessor cores, which might potentially be waiting idle on the system.

To simulate long-lasting operations, the following examples call Thread.sleep() from the core.thread module. Thread.sleep() suspends the operations for the specified amount of time. Thread.sleep is admittedly an artifical method to use in the following examples because it takes time without ever busying any core. Despite being an unrealistic tool, it is still useful in this chapter to demonstrate the power of parallelism.

import std.stdio; import core.thread; struct Student { int number; void aSlowOperation() { writefln( "The work on student %s has begun" , number); Thread.sleep(1.seconds); writefln( "The work on student %s has ended" , number); } } void main() { auto students = [ Student(1), Student(2), Student(3), Student(4) ]; foreach (student; students) { student.aSlowOperation(); } }

The execution time of the program can be measured in a terminal by time :

$ time ./deneme The work on student 1 has begun The work on student 1 has ended The work on student 2 has begun The work on student 2 has ended The work on student 3 has begun The work on student 3 has ended The work on student 4 has begun The work on student 4 has ended real 0m4.005s ← 4 seconds total user 0m0.004s sys 0m0.000s

Since the students are iterated over in sequence and since the work of each student takes 1 second, the total execution time comes out to be 4 seconds. However, if these operations were executed in an environment that had 4 cores, they could be operated on at the same time and the total time would be reduced to about 1 second.

Before seeing how this is done, let's first determine the number of cores that are available on the system by std.parallelism.totalCPUs :

import std.stdio; import std.parallelism; void main() { writefln( "There are %s cores on this system." , totalCPUs); }

The output of the program in the environment that this chapter has been written is the following:

There are 4 cores on this system.

This function can also be called simply as parallel() .

parallel() accesses the elements of a range in parallel. An effective usage is with foreach loops. Merely importing the std.parallelism module and replacing students with parallel(students) in the program above is sufficient to take advantage of all of the cores of the system:

import std.parallelism; foreach (student; parallel(students) ) {

We have seen earlier in the foreach for structs and classes chapter that the expressions that are in foreach blocks are passed to opApply() member functions as delegates. parallel() returns a range object that knows how to distribute the execution of the delegate to a separate core for each element.

As a result, passing the Student range through parallel() makes the program above finish in 1 second on a system that has 4 cores:

$ time ./deneme The work on student 2 has begun The work on student 1 has begun The work on student 4 has begun The work on student 3 has begun The work on student 1 has ended The work on student 2 has ended The work on student 4 has ended The work on student 3 has ended real 0m1.005s ← now only 1 second user 0m0.004s sys 0m0.004s

Note: The execution time of the program may be different on other systems but it is expected to be roughly "4 seconds divided by the number of cores".

A flow of execution through certain parts of a program is called a a thread of execution or a thread. Programs can consist of multiple threads that are being actively executed at the same time. The operating system starts and executes each thread on a core and then suspends it to execute other threads. The execution of each thread may involve many cycles of starting and suspending.

All of the threads of all of the programs that are active at a given time are executed on the very cores of the microprocessor. The operating system decides when and under what condition to start and suspend each thread. That is the reason why the messages that are printed by aSlowOperation() are in mixed order in the output above. This undeterministic order of thread execution may not matter if the operations of the Student objects are truly independent from each other.

It is the responsibility of the programmer to call parallel() only when the operations applied to each element are independent for each iteration. For example, if it were important that the messages appear in a certain order in the output, calling parallel() should be considered an error in the program above. The programming model that supports threads that depend on other threads is called concurrency. Concurrency is the topic of the next chapter.

By the time parallel foreach ends, all of the operations inside the loop have been completed for all of the elements. The program can safely continue after the foreach loop.

Work unit size

The second parameter of parallel() has an overloaded meaning and is ignored in some cases:

= parallel(range, work_unit_size = 100);

When iterating over RandomAccessRange ranges: The distribution of threads to cores has some minimal cost. This cost may sometimes be significant especially when the operations of the loop are completed in a very short time. In such cases, it may be faster to have each thread execute more than one iteration of the loop. The work unit size determines the number of elements that each thread should execute at each of its iterations: foreach (student; parallel(students, 2 )) { } The default value of work unit size is 100 and is suitable for most cases.

ranges: When iterating over non- RandomAccessRange ranges: parallel() does not start parallel executions until work unit size number of elements of a non- RandomAccessRange have been executed serially first. Due to the relatively high value of 100, parallel() may give the wrong impression that it is not effective when tried on short non- RandomAccessRange ranges.

ranges: When iterating over the result ranges of asyncBuf() or parallel map() (both are explained later in this chapter): When parallel() works on the results of asyncBuf() or map() , it ignores the work unit size parameter. Instead, parallel() reuses the internal buffer of the result range.

Task

Operations that are executed in parallel with other operations of a program are called tasks. Tasks are represented by the type std.parallelism.Task .

In fact, parallel() constructs a new Task object for every worker thread and starts that task automatically. parallel() then waits for all of the tasks to be completed before finally exiting the loop. parallel() is very convenient as it constructs, starts, and waits for the tasks automatically.

When tasks do not correspond to or cannot be represented by elements of a range, these three steps can be handled explicitly by the programmer. task() constructs, executeInNewThread() starts, and yieldForce() waits for a task object. These three functions are explained further in the comments of the following program.

The anOperation() function is started twice in the following program. It prints the first letter of id to indicate which task it is working for.

Note: Normally, the characters that are printed to output streams like stdout do not appear on the output right away. They are instead stored in an output buffer until a line of output is completed. Since write does not output a new-line character, in order to observe the parallel execution of the following program, stdout.flush() is called to send the contents of the buffer to stdout even before reaching the end of a line.

import std.stdio; import std.parallelism; import std.array; import core.thread; int anOperation(string id, int duration) { writefln( "%s will take %s seconds" , id, duration); foreach (i; 0 .. (duration * 2)) { Thread.sleep(500.msecs); write(id.front); stdout.flush(); } return 1; } void main() { auto theTask = task!anOperation ( "theTask" , 5); theTask. executeInNewThread() ; immutable result = anOperation( "main's call" , 3); immutable taskResult = theTask. yieldForce() ; writeln(); writefln( "All finished; the result is %s." , result + taskResult); }

The output of the program should be similar to the following. The fact that the m and t letters are printed in mixed order indicates that the operations are executed in parallel:

main's call will take 3 seconds theTask will take 5 seconds mtmttmmttmmttttt All finished; the result is 2.

The task function above has been specified as a template parameter to task() as task!anOperation . Although this method works well in most cases, as we have seen in the Templates chapter, each different instantiation of a template is a different type. This distinction may be undesirable in certain situations where seemingly equivalent task objects would actually have different types.

For example, although the following two functions have the same signature, the two Task instantiations that are produced through calls to the task() function template would have different types. As a result, they cannot be members of the same array:

import std.parallelism; double foo( int i) { return i * 1.5; } double bar( int i) { return i * 2.5; } void main() { auto tasks = [ task ! foo(1), task ! bar(2) ]; }

Error: incompatible types for ((task(1)) : (task(2))): 'Task!( foo , int)*' and 'Task!( bar , int)*'

Another overload of task() takes the function as its first function parameter instead:

void someFunction( int value) { } auto theTask = task( &someFunction , 42);

As this method does not involve different instantiations of the Task template, it makes it possible to put such objects in the same array:

import std.parallelism; double foo( int i) { return i * 1.5; } double bar( int i) { return i * 2.5; } void main() { auto tasks = [ task( & foo, 1), task( & bar, 2) ]; }

A lambda function or an object of a type that defines the opCall member can also be used as the task function. The following example starts a task that executes a lambda:

auto theTask = task(( int value) { } , 42);

Exceptions

As tasks are executed on separate threads, the exceptions that they throw cannot be caught by the thread that started them. For that reason, the exceptions that are thrown are automatically caught by the tasks themselves, to be rethrown later when Task member functions like yieldForce() are called. This makes it possible for the main thread to catch exceptions that are thrown by a task.

import std.stdio; import std.parallelism; import core.thread; void mayThrow() { writeln( "mayThrow() is started" ); Thread.sleep(1.seconds); writeln( "mayThrow() is throwing an exception" ); throw new Exception( "Error message" ); } void main() { auto theTask = task!mayThrow(); theTask.executeInNewThread(); writeln( "main is continuing" ); Thread.sleep(3.seconds); writeln( "main is waiting for the task" ); theTask.yieldForce(); }

The output of the program shows that the uncaught exception that has been thrown by the task does not terminate the entire program right away (it terminates only the task):

main is continuing mayThrow() is started mayThrow() is throwing an exception ← thrown main is waiting for the task object.Exception@deneme.d(10): Error message ← terminated

yieldForce() can be called in a try-catch block to catch the exceptions that are thrown by the task. Note that this is different from single threads: In single-threaded programs like the samples that we have been writing until this chapter, try-catch wraps the code that may throw. In parallelism, it wraps yieldForce() :

try { theTask.yieldForce(); } catch (Exception exc) { writefln( "Detected an error in the task: '%s'" , exc.msg); }

This time the exception is caught by the main thread instead of terminating the program:

main is continuing mayThrow() is started mayThrow() is throwing an exception ← thrown main is waiting for the task Detected an error in the task: 'Error message' ← caught

Member functions of Task

done : Specifies whether the task has been completed; rethrows the exception if the task has been terminated with an exception. if (theTask.done) { writeln( "Yes, the task has been completed" ); } else { writeln( "No, the task is still going on" ); }

: Specifies whether the task has been completed; rethrows the exception if the task has been terminated with an exception. executeInNewThread() : Starts the task in a new thread.

: Starts the task in a new thread. executeInNewThread(int priority) : Starts the task in a new thread with the specified priority. (Priority is an operating system concept that determines execution priorities of threads.)

There are three functions to wait for the completion of a task:

yieldForce() : Starts the task if it has not been started yet; if it has already been completed, returns its return value; if it is still running, waits for its completion without making the microprocessor busy; if an exception has been thrown, rethrows that exception.

: Starts the task if it has not been started yet; if it has already been completed, returns its return value; if it is still running, waits for its completion without making the microprocessor busy; if an exception has been thrown, rethrows that exception. spinForce() : Works similarly to yieldForce() , except that it makes the microprocessor busy while waiting, in order to catch the completion as early as possible.

: Works similarly to , except that it makes the microprocessor busy while waiting, in order to catch the completion as early as possible. workForce() : Works similarly to yieldForce() , except that it starts a new task in the current thread while waiting for the task to be completed.

In most cases yieldForce() is the most suitable function to call when waiting for a task to complete; it suspends the thread that calls yieldForce() until the task is completed. Although spinForce() makes the microprocessor busy while waiting, it is suitable when the task is expected to be completed in a very short time. workForce() can be called when starting other tasks is preferred over suspending the current thread.

Please see the online documentation of Phobos for the other member functions of Task .

Similarly to parallel() , asyncBuf() iterates InputRange ranges in parallel. It stores the elements in a buffer as they are produced by the range, and serves the elements from that buffer to its user.

In order to avoid making a potentially fully-lazy input range a fully-eager range, it iterates the elements in waves. Once it prepares certain number of elements in parallel, it waits until those elements are consumed by popFront() before producing the elements of the next wave.

asyncBuf() takes a range and an optional buffer size that determines how many elements to be made available during each wave:

auto elements = taskPool.asyncBuf(range, buffer_size);

To see the effects of asyncBuf() , let's use a range that takes half a second to iterate and half a second to process each element. This range simply produces integers up to the specified limit:

import std.stdio; import core.thread; struct Range { int limit; int i; bool empty() const { return i >= limit; } int front() const { return i; } void popFront() { writefln( "Producing the element after %s" , i); Thread.sleep(500.msecs); ++i; } } void main() { auto range = Range(10); foreach (element; range) { writefln( "Using element %s" , element); Thread.sleep(500.msecs); } }

The elements are produced and used lazily. Since it takes one second for each element, the whole range takes ten seconds to process in this program:

$ time ./deneme Using element 0 Producing the element after 0 Using element 1 Producing the element after 1 Using element 2 ... Producing the element after 8 Using element 9 Producing the element after 9 real 0m10.007s ← 10 seconds total user 0m0.004s sys 0m0.000s

According to that output, the elements are produced and used sequentially.

On the other hand, it may not be necessary to wait for preceding elements to be processed before starting to produce the successive elements. The program would take less time if other elements could be produced while the front element is in use:

import std.parallelism; foreach (element; taskPool.asyncBuf (range, 2 )) {

In the call above, asyncBuf() makes two elements ready in its buffer. Elements are produced in parallel while they are being used:

$ time ./deneme Producing the element after 0 Producing the element after 1 Using element 0 Producing the element after 2 Using element 1 Producing the element after 3 Using element 2 Producing the element after 4 Using element 3 Producing the element after 5 Using element 4 Producing the element after 6 Producing the element after 7 Using element 5 Using element 6 Producing the element after 8 Producing the element after 9 Using element 7 Using element 8 Using element 9 real 0m6.007s ← now 6 seconds user 0m0.000s sys 0m0.004s

The default value of buffer size is 100. The buffer size that produces the best performance would be different under different situations.

asyncBuf() can be used outside of foreach loops as well. For example, the following code uses the return value of asyncBuf() as an InputRange which operates semi-eagerly:

auto range = Range(10); auto asyncRange = taskPool.asyncBuf(range, 2); writeln( asyncRange.front );

It helps to explain map() from the std.algorithm module before explaining taskPool.map() . std.algorithm.map is an algorithm commonly found in many functional languages. It calls a function with the elements of a range one-by-one and returns a range that consists of the results of calling that function with each element. It is a lazy algorithm: It calls the function as needed. (There is also std.algorithm.each , which is for generating side effects for each element, as opposed to producing a result from it.)

The fact that std.algorithm.map operates lazily is very powerful in many programs. However, if the function needs to be called with every element anyway and the operations on each element are independent from each other, laziness may be unnecessarily slower than parallel execution. taskPool.map() and taskPool.amap() from the std.parallelism module take advantage of multiple cores and run faster in many cases.

Let's compare these three algorithms using the Student example. Let's assume that Student has a member function that returns the average grade of the student. To demonstrate how parallel algorithms are faster, let's again slow this function down with Thread.sleep() .

std.algorithm.map takes the function as its template parameter, and the range as its function parameter. It returns a range that consists of the results of applying that function to the elements of the range:

auto result_range = map!func(range);

The function may be specified by the => syntax as a lambda expression as we have seen in earlier chapters. The following program uses map() to call the averageGrade() member function on each element:

import std.stdio; import std.algorithm; import core.thread; struct Student { int number; int [] grades; double averageGrade() { writefln( "Started working on student %s" , number); Thread.sleep(1.seconds); const average = grades.sum / grades.length; writefln( "Finished working on student %s" , number); return average; } } void main() { Student[] students; foreach (i; 0 .. 10) { students ~= Student(i, [80 + i, 90 + i]); } auto results = map !(a => a.averageGrade)(students); foreach (result; results) { writeln(result); } }

The output of the program demonstrates that map() operates lazily; averageGrade() is called for each result as the foreach loop iterates:

$ time ./deneme Started working on student 0 Finished working on student 0 85 ← calculated as foreach iterates Started working on student 1 Finished working on student 1 86 ... Started working on student 9 Finished working on student 9 94 real 0m10.006s ← 10 seconds total user 0m0.000s sys 0m0.004s

If std.algorithm.map were an eager algorithm, the messages about the starts and finishes of the operations would be printed altogether at the top.

taskPool.map() from the std.parallelism module works essentially the same as std.algorithm.map . The only difference is that it executes the function calls semi-eagerly and stores the results in a buffer to be served from as needed. The size of this buffer is determined by the second parameter. For example, the following code would make ready the results of the function calls for three elements at a time:

import std.parallelism; double averageGrade(Student student) { return student.averageGrade; } auto results = taskPool.map !averageGrade(students, 3 );

Note: The free-standing averageGrade() function above is needed due to a limitation that involves using local delegates with member function templates like TaskPool.map . There would be a compilation error without that free-standing function:

auto results = taskPool.map!(a => a.averageGrade)(students, 3);

This time the operations are executed in waves of three elements:

$ time ./deneme Started working on student 1 ← in parallel Started working on student 2 ← but in unpredictable order Started working on student 0 Finished working on student 1 Finished working on student 2 Finished working on student 0 85 86 87 Started working on student 4 Started working on student 5 Started working on student 3 Finished working on student 4 Finished working on student 3 Finished working on student 5 88 89 90 Started working on student 7 Started working on student 8 Started working on student 6 Finished working on student 7 Finished working on student 6 Finished working on student 8 91 92 93 Started working on student 9 Finished working on student 9 94 real 0m4.007s ← 4 seconds total user 0m0.000s sys 0m0.004s

The second parameter of map() has the same meaning as asyncBuf() : It determines the size of the buffer that map() uses to store the results in. The third parameter is the work unit size as in parallel() ; the difference being its default value, which is size_t.max :

= taskPool.map!func(range, buffer_size = 100 work_unit_size = size_t.max);

Parallel amap() works the same as parallel map() with two differences:

It is fully eager.

It works with RandomAccessRange ranges.

auto results = taskPool.amap !averageGrade(students);

Since it is eager, all of the results are ready by the time amap() returns:

$ time ./deneme Started working on student 1 ← all are executed up front Started working on student 0 Started working on student 2 Started working on student 3 Finished working on student 1 Started working on student 4 Finished working on student 2 Finished working on student 3 Started working on student 6 Finished working on student 0 Started working on student 7 Started working on student 5 Finished working on student 4 Started working on student 8 Finished working on student 6 Started working on student 9 Finished working on student 7 Finished working on student 5 Finished working on student 8 Finished working on student 9 85 86 87 88 89 90 91 92 93 94 real 0m3.005s ← 3 seconds total user 0m0.000s sys 0m0.004s

amap() works faster than map() at the expense of using an array that is large enough to store all of the results. It consumes more memory to gain speed.

The optional second parameter of amap() is the work unit size as well:

auto results = taskPool.amap!averageGrade(students, 2 );

The results can also be stored in a RandomAccessRange that is passed to amap() as its third parameter:

double [] results; results.length = students.length; taskPool.amap!averageGrade(students, 2, results );

As with map() , it helps to explain reduce() from the std.algorithm module first.

reduce() is the equivalent of std.algorithm.fold , which we have seen before in the Ranges chapter. The main difference between the two is that their function parameters are reversed. (For that reason, I recommend that you prefer fold() for non-parallel code as it can take advantage of UFCS in chained range expressions.)

reduce() is another high-level algorithm commonly found in many functional languages. Just like map() , it takes one or more functions as template parameters. As its function parameters, it takes a value to be used as the initial value of the result, and a range. reduce() calls the functions with the current value of the result and each element of the range. When no initial value is specified, the first element of the range is used instead.

Assuming that it defines a variable named result in its implementation, the way that reduce() works can be described by the following steps:

Assigns the initial value to result Executes the expression result = func(result, element) for every element Returns the final value of result

For example, the sum of the squares of the elements of an array can be calculated as in the following program:

import std.stdio; import std.algorithm; void main() { writeln(reduce!((a, b) => a + b * b)(0, [5, 10])); }

When the function is specified by the => syntax as in the program above, the first parameter (here a ) represents the current value of the result (initialized by the parameter 0 above) and the second parameter (here b ) represents the current element.

The program outputs the sum of 25 and 100, the squares of 5 and 10:

125

As obvious from its behavior, reduce() uses a loop in its implementation. Because that loop is normally executed on a single core, it may be unnecessarily slow when the function calls for each element are independent from each other. In such cases taskPool.reduce() from the std.parallelism module can be used for taking advantage of all of the cores.

To see an example of this let's use reduce() with a function that is slowed down again artificially:

import std.stdio; import std.algorithm; import core.thread; int aCalculation( int result, int element) { writefln( "started - element: %s, result: %s" , element, result); Thread.sleep(1.seconds); result += element; writefln( "finished - element: %s, result: %s" , element, result); return result; } void main() { writeln( "Result: " , reduce !aCalculation(0, [1, 2, 3, 4])); }

reduce() uses the elements in sequence to reach the final value of the result:

$ time ./deneme started - element: 1, result: 0 finished - element: 1, result: 1 started - element: 2, result: 1 finished - element: 2, result: 3 started - element: 3, result: 3 finished - element: 3, result: 6 started - element: 4, result: 6 finished - element: 4, result: 10 Result: 10 real 0m4.003s ← 4 seconds total user 0m0.000s sys 0m0.000s

As in the parallel() and map() examples, importing the std.parallelism module and calling taskPool.reduce() is sufficient to take advantage of all of the cores:

import std.parallelism; writeln( "Result: " , taskPool.reduce !aCalculation(0, [1, 2, 3, 4]));

However, there are important differences in the way taskPool.reduce() works.

Like the other parallel algorithms, taskPool.reduce() executes the functions in parallel by using elements in different tasks. Each task works on the elements that it is assigned to and calculates a result that corresponds to the elements of that task. Since reduce() is called with only a single initial value, every task must use that same initial value to initialize its own result (the parameter 0 above).

The final values of the results that each task produces are themselves used in the same result calculation one last time. These final calculations are executed sequentially, not in parallel. For that reason, taskPool.reduce() may execute slower in short examples as in this chapter as will be observed in the following output.

The fact that the same initial value is used for all of the tasks, effectively being used in the calculations multiple times, taskPool.reduce() may calculate a result that is different from what std.algorithm.reduce() calculates. For that reason, the initial value must be the identity value for the calculation that is being performed, e.g. the 0 in this example which does not have any effect in addition.

Additionally, as the results are used by the same functions one last time in the sequential calculations, the types of the parameters that the functions take must be compatible with the types of the values that the functions return.

taskPool.reduce() should be used only under these considerations.

import std.parallelism; writeln( "Result: " , taskPool.reduce !aCalculation(0, [1, 2, 3, 4]));

The output of the program indicates that first the calculations are performed in parallel, and then their results are calculated sequentially. The calculations that are performed sequentially are highlighted:

$ time ./deneme started - element: 3, result: 0 ← first, the tasks in parallel started - element: 2, result: 0 started - element: 1, result: 0 started - element: 4, result: 0 finished - element: 3, result: 3 finished - element: 1, result: 1 started - element: 1, result: 0 ← then, their results sequentially finished - element: 4, result: 4 finished - element: 2, result: 2 finished - element: 1, result: 1 started - element: 2, result: 1 finished - element: 2, result: 3 started - element: 3, result: 3 finished - element: 3, result: 6 started - element: 4, result: 6 finished - element: 4, result: 10 Result: 10 real 0m5.006s ← parallel reduce is slower in this example user 0m0.004s sys 0m0.000s

Parallel reduce() is faster in many other calculations like the calculation of the math constant pi (π) by quadrature.

Multiple functions and tuple results

std.algorithm.map() , taskPool.map() , taskPool.amap() , and taskPool.reduce() can all take more than one function, in which case the results are returned as a Tuple . We have seen the Tuple type in the Tuples chapter before. The results of individual functions correspond to the elements of the tuple in the order that the functions are specified. For example, the result of the first function is the first member of the tuple.

The following program demonstrates multiple functions with std.algorithm.map . Note that the return types of the functions need not be the same, as seen in the quarterOf() and tenTimes() functions below. In that case, the types of the members of the tuples would be different as well:

import std.stdio; import std.algorithm; import std.conv; double quarterOf( double value) { return value / 4; } string tenTimes( double value) { return to!string(value * 10); } void main() { auto values = [10, 42, 100]; auto results = map!( quarterOf, tenTimes )(values); writefln( " Quarters Ten Times" ); foreach (quarterResult, tenTimesResult; results) { writefln( "%8.2f%8s" , quarterResult, tenTimesResult); } }

The output:

Quarters Ten Times 2.50 100 10.50 420 25.00 1000

In the case of taskPool.reduce() , the initial values of the results must be specified as a tuple:

taskPool.reduce!(foo, bar)( tuple(0, 1) , [1, 2, 3, 4]);

TaskPool

Behind the scenes, the parallel algorithms from the std.parallelism module all use task objects that are elements of a TaskPool container. Normally, all of the algorithms use the same container object named taskPool .

taskPool contains appropriate number of tasks depending on the environment that the program runs under. For that reason, usually there is no need to create any other TaskPool object. Even so, explicit TaskPool objects may be created and used as needed.

The TaskPool constructor takes the number of threads to use during the parallel operations that are later started through it. The default value of the number of threads is one less than the number of cores on the system. All of the features that we have seen in this chapter can be applied to a separate TaskPool object.

The following example calls parallel() on a local TaskPool object:

import std.stdio; import std.parallelism; void main() { auto workers = new TaskPool(2) ; foreach (i; workers .parallel([1, 2, 3, 4])) { writefln( "Working on %s" , i); } workers .finish(); }

TaskPool.finish() tells the object to stop processing when all of its current tasks are completed.

Summary