Merge pull request #95 from dzenanz/master

ENH: mention work units and use ProgressTransformer in the example

Author: thewtex

SoftwareGuide/Latex/Architecture/SystemOverview.tex

@@ -407,7 +407,7 @@ \subsection{Multi-Threading}
 that do not overlap for write operations.
 \code{ImageSource}'s \code{GenerateData()} passes \code{this} pointer
 to \code{ParallelizeImageRegion}, which allows \code{ParallelizeImageRegion}
-to update the filter's progress after each region is finished processing.
+to update the filter's progress after each region has been processed.
 
 If a filter has some serial part in the middle, in addition to initialization
 done in \code{BeforeThreadedGenerateData()} and finalization done in
@@ -424,19 +424,21 @@ \subsection{Multi-Threading}
   // Small serial section
   this->UpdateProgress(0.01f);
 
+  ProgressTransformer progress1( 0.01f, 0.45f, this );
   // Calculate 2nd order directional derivative
   this->GetMultiThreader()->template ParallelizeImageRegion<TOutputImage::ImageDimension>(
       this->GetOutput()->GetRequestedRegion(),
       [this](const OutputImageRegionType & outputRegionForThread)
-      { this->ThreadedCompute2ndDerivative(outputRegionForThread); }, nullptr);
-  this->UpdateProgress(0.45f);
+      { this->ThreadedCompute2ndDerivative(outputRegionForThread); },
+      progress1.GetProcessObject());
 
+  ProgressTransformer progress2( 0.45f, 0.9f, this );
   // Calculate the gradient of the second derivative
   this->GetMultiThreader()->template ParallelizeImageRegion<TOutputImage::ImageDimension>(
       this->GetOutput()->GetRequestedRegion(),
       [this](const OutputImageRegionType & outputRegionForThread)
-      { this->ThreadedCompute2ndDerivativePos(outputRegionForThread); }, nullptr);
-  this->UpdateProgress(0.9f);
+      { this->ThreadedCompute2ndDerivativePos(outputRegionForThread); },
+      progress2.GetProcessObject());
 
   // More processing
   this->UpdateProgress(1.0f);
@@ -445,12 +447,13 @@ \subsection{Multi-Threading}
 \normalsize
 
 When invoking \code{ParallelizeImageRegion} multiple times from
-\code{GenerateData()}, \code{nullptr} should be passed instead of \code{this},
+\code{GenerateData()}, either \code{nullptr} or a
+\doxygen{ProgressTransformer} object should be passed instead of \code{this},
 otherwise progress will go from 0\% to 100\% more than once. And this
 will at least confuse any other class watching the filter's progress events,
 even if it does not cause a crash. So the filter's author should estimate
-how long each part of \code{GenerateData()} takes, and update the progress
-``manually'' as in the example above.
+how long each part of \code{GenerateData()} takes, and construct and pass
+\code{ProgressTransformer} objects as in the example above.
 
 With ITK version 5.0, the Multi-Threading mechanism has been refactored.
 What was previously \code{itk::MultiThreader}, is now a hierarchy of classes.
@@ -470,6 +473,15 @@ \subsection{Multi-Threading}
 the filter's user or downstream filter in the pipeline. The best place for
 invoking \code{this->DynamicMultiThreadingOff();} is the filter's constructor.
 
+In image filters and other descendants of \code{ProcessObject}, method
+\code{SetNumberOfWorkUnits} controls the level of parallelism.
+Load balancing is possible when \code{NumberOfWorkUnits} is greater
+than the number of threads. In most places where developer would like to
+restrict number of threads, work units should be changed instead.
+\doxygen{MultiThreaderBase}'s \code{MaximumNumberOfThreads} should not
+generally be changed, except when testing performance and scalability,
+profiling and sometimes debugging code.
+
 The general philosophy in ITK regarding thread safety is that accessing
 different instances of a class (and its methods) is a thread-safe operation.
 Invoking methods on the same instance in different threads is to be avoided.

SoftwareGuide/Latex/DevelopmentGuidelines/WriteAFilter.tex

@@ -473,14 +473,16 @@ \section{Threaded Filter Execution}
 
 Multi-threading requires caution when performing I/O (including using
 \code{cout} or \code{cerr}) or invoking events. A safe practice is to allow
-only thread id zero to perform I/O or generate events. (The thread id is
-passed as argument into \code{ThreadedGenerateData(Region, ThreadId)}).
+only the invoking thread to perform I/O or generate events.
 If more than one thread tries to write to the same place at the same time,
 the program can behave badly, and possibly even deadlock or crash.
 
-Filters which need thread identifier (id) should implement the
-\code{ThreadedGenerateData(Region, ThreadId)} method and call
-\code{this->DynamicMultiThreadingOff();} in the filter's constructor.
+\code{DynamicThreadedGenerateData} signature allows number of pieces
+(output regions) to be processed to be different, usually bigger than the
+number of real threads executing the work. In turn, this allows load
+balancing. The number of work units controls filter parallelism,
+and the name `threads' is reserved for real threads as exposed by
+\doxygen{MultiThreaderBase} and its descendants.