Multi-Threaded LoopBuilder

[maarzt]

This PR improves the performance of LoopBuilder by adding two features:

1. LoopBuilder now supports multi-threading. This example copies an image using multiple threads:

LoopBuilder.setImages(imageA, imageB).multiThreaded().forEachPixel(
    (a, b) -> b.set(a)
);

2. In certain circumstances LoopBuilder uses Cursor instead of RandomAccess to iterate over an image. This happens when all images are NativeImg like ArrayImg, PlanarImg and CellImg.

The multiThreaded() method in the example above optionally accepts a MultiThreadSetting argument:

MultiThreadSetting mts = MultiThreadSettings.multi();
LoopBuilder.setImages(imageA, imageB).multiThreaded(mts).forEachPixel(
    (a, b) -> b. set(a)
);

Using the MultiThreadSetting one can specify how LoopBuilder does the multi-threading. MultiThreadedSettings.single() will make the algorithm run without multi-threading, this is also the default. MultiThreadSettings.multi() does multi-threading. It's also possible to specify the ExecutorService to be used MultiThreadSettings.multi(16, Executors.newFixedThreadPool(8)). MultiThreadSetting is a very simple interface, have a look. If you want LoopBuilder to use a specific thread pool, an custom implementation of MultiThreadSetting is the solution.

I think MultiThreadSetting can be very useful for image processing algorithms, so I'm happy to discuss it.

[imagejan]

Why the plural S here?

[maarzt]

That's a typo, should be without the S ;)

[ctrueden]

Is it worth looking at using ForkJoinPool instead, as discussed in imglib/imglib2-algorithm#81?

[maarzt]

MultiThreadSetting is now package-private, and therefore hidden to the user.
We can now merge this PR, to get the multi-threaded LoopBuilder. And after the discussion
about a unified strategy for multi-threading, we can easily change MultiThreadSetting and LoopBuilder.

@tpietzsch How do you feel about merging this PR?

[maarzt]

@tpietzsch What do you think. Can we merge this?

[acardona]

Hi @maarzt,
Question: does this partition the tasks by pixels, that is, two consecutive pixels are processed by different threads? If so, does performance degrade substantially from a larger partitioning approach, whereby instead of processing each pixel independently, a contiguous chunk of the source image is processed by a single thread, so the whole source image is split into as many partitions as there are threads? I suspect the latter has far better performance, given that memory may not be contiguous in large images.

[maarzt]

@acardona

Question: does this partition the tasks by pixels, that is, two consecutive pixels are processed by different threads?

No, consecutive pixels are usually processed by the same thread. The PR also contains a benchmark that shows multi-threading performance: https://github.com/imglib/imglib2/blob/multithreaded-loop-builder/src/test/java/net/imglib2/loops/LoopPerformanceBenchmark.java
I get a multi-threading speedup of 3.8 on my 4 core machine.

[acardona]

Thanks, a 3.8x speed up is wonderful.