Merge pull request #2951 from PaulBoersma/master

guide for how to parallelize an existing function

Author: PaulBoersma

fon/Sound_to_Pitch.cpp

@@ -436,7 +436,7 @@ autoPitch Sound_to_Pitch_any (Sound me,
 
 		autoMelderProgress progress (U"Sound to Pitch...");
 
-		MelderThread_PARALLELIZE(numberOfFrames, 5, false, threadNumber)
+		MelderThread_PARALLELIZE (numberOfFrames, 5, false, threadNumber)
 
 		autoMAT frame;
 		autoNUMFourierTable fftTable;
@@ -453,7 +453,7 @@ autoPitch Sound_to_Pitch_any (Sound me,
 		autoINTVEC imax = zero_INTVEC (maxnCandidates);
 		autoVEC localMean = zero_VEC (my ny);
 
-		MelderThread_FOR (iframe)
+		MelderThread_FOR (iframe) {
 
 			Pitch_Frame pitchFrame = & thy frames [iframe];
 			const double time = Sampled_indexToX (thee.get(), iframe);
@@ -473,7 +473,7 @@ autoPitch Sound_to_Pitch_any (Sound me,
 				r, imax.get(), localMean.get()
 			);
 
-		MelderThread_ENDFOR
+		} MelderThread_ENDFOR
 
 		Melder_progress (0.95, U"Sound to Pitch: path finder");
 		Pitch_pathFinder (thee.get(), silenceThreshold, voicingThreshold,

melder/MelderThread.h

@@ -214,7 +214,7 @@ void MelderThread_run (
 				autoINTVEC imax = zero_INTVEC (maxnCandidates);
 				autoVEC localMean = zero_VEC (my ny);
 
-				MelderThread_FOR (iframe)
+				MelderThread_FOR (iframe) {
 
 					Pitch_Frame pitchFrame = & thy frames [iframe];
 					Sound_into_PitchFrame (me, pitchFrame, maxnCandidates,
@@ -231,7 +231,7 @@ void MelderThread_run (
 						);
 					}
 
-				MelderThread_ENDFOR
+				} MelderThread_ENDFOR
 
 				Melder_progress (0.95, U"Sound to Pitch: path finder");
 				return thee;
@@ -241,5 +241,86 @@ void MelderThread_run (
 		}
 */
 
+/*
+	How to parallelize an existing analysis function
+	================================================
+
+	Suppose you have something like
+
+	autoPitch Sound_to_Pitch (Sound me) {
+		try {
+			autoPitch thee = ...;
+			autoVEC window = ...;   // the window shape
+			autoMAT frame = zero_MAT (my ny, ...);
+			autoNUMFourierTable fftTable = NUMFourierTable_create (...);
+			autoVEC ac = zero_VEC (...);
+			autoVEC rbuffer = zero_VEC (...);
+			double *r = & rbuffer [...];
+			autoVEC windowR = ...;   // the autocorrelation of the window shape
+			autoINTVEC imax = zero_INTVEC (maxnCandidates);
+			autoVEC localMean = zero_VEC (my ny);
+			autoMelderProgress progress (U"Sound to Pitch...");
+			for (integer iframe = 1; iframe <= thy nx; iframe ++) {
+				Pitch_Frame pitchFrame = & thy frames [iframe];
+				const double fractionAnalysed = (double) iframe / thy nx;
+				Melder_progress (0.1 + 0.8 * fractionAnalysed,
+					U"Sound to Pitch: analysed ", iframe,
+					U" out of ", thy nx, U" frames"
+				);
+				Sound_into_PitchFrame (me, pitchFrame, maxnCandidates,
+					window.get(), windowR.get(),
+					frame.get(), fftTable.get(), ac.get(),
+					r, imax.get(), localMean.get()
+				);
+			}
+			Melder_progress (0.95, U"Sound to Pitch: path finder");
+			return thee;
+		} catch (MelderError) {
+			Melder_throw (me, U": pitch analysis not performed.");
+		}
+	}
+
+	The first step is to divide all those initializations into two sets:
+	1. the ones that all threads can use at the same time;
+	   these are:
+	   1a. the target Pitch object, because each threads will write a separate part of it:
+			autoPitch thee = ...;
+	   1b. the "constant" things that are computed only once, before the loop over the frames:
+			autoVEC window = ...;   // the window shape
+			autoVEC windowR = ...;   // the autocorrelation of the window shape
+	   1c. the initialization of the progress bar:
+			autoMelderProgress progress (U"Sound to Pitch...");
+	2. the ones of which each thread need its own copy, like buffers:
+			autoMAT frame = zero_MAT (my ny, ...);
+			autoNUMFourierTable fftTable = NUMFourierTable_create (...);
+			autoVEC ac = zero_VEC (...);
+			autoVEC rbuffer = zero_VEC (...);
+			double *r = & rbuffer [...];
+			autoINTVEC imax = zero_INTVEC (maxnCandidates);
+			autoVEC localMean = zero_VEC (my ny);
+
+	This reordering is the preparation. You then make the following simple changes:
+	3. between 1abc and 2 above you insert:
+			MelderThread_PARALLELIZE (thy nx, 5, false, threadNumber)
+	4. instead of
+			for (integer iframe = 1; iframe <= thy nx; iframe ++) {
+	   you write
+			MelderThread_FOR (iframe) {
+	5. instead of the frame-loop-closing "}" you write
+			} MelderThread_ENDFOR
+	6. you update the progress bar only in the master thread, by inserting
+			if (threadNumber == 0) {
+	   and
+			}
+	7. instead of computing the progress as
+				const double fractionAnalysed = (double) iframe / thy nx;
+	   you write
+				const double fractionAnalysed = MelderThread_ESTIMATE_PROGRESS (iframe);
+	   and you may reword the variable name and the text to acknowledge that this progress
+	   is just an estimate;
+	8. you tune the "thresholdNumberOfElementsPerThread" to what turns out to be fastest
+	   for low numbers of threads; see `manually/Sound_to_Pitch.praat` for an example.
+*/
+
 /* End of file MelderThread.h */
 #endif