cannam@95: Next: How Many Threads to Use?, cannam@95: Previous: Installation and Supported Hardware/Software, cannam@95: Up: Multi-threaded FFTW cannam@95:
Here, it is assumed that the reader is already familiar with the usage cannam@95: of the uniprocessor FFTW routines, described elsewhere in this manual. cannam@95: We only describe what one has to change in order to use the cannam@95: multi-threaded routines. cannam@95: cannam@95:
First, programs using the parallel complex transforms should be linked
cannam@95: with -lfftw3_threads -lfftw3 -lm on Unix, or -lfftw3_omp
cannam@95: -lfftw3 -lm if you compiled with OpenMP. You will also need to link
cannam@95: with whatever library is responsible for threads on your system
cannam@95: (e.g. -lpthread on GNU/Linux) or include whatever compiler flag
cannam@95: enables OpenMP (e.g. -fopenmp with gcc).
cannam@95:
cannam@95:
cannam@95:
Second, before calling any FFTW routines, you should call the cannam@95: function: cannam@95: cannam@95:
int fftw_init_threads(void); cannam@95:cannam@95:
cannam@95: This function, which need only be called once, performs any one-time cannam@95: initialization required to use threads on your system. It returns zero cannam@95: if there was some error (which should not happen under normal cannam@95: circumstances) and a non-zero value otherwise. cannam@95: cannam@95:
Third, before creating a plan that you want to parallelize, you should cannam@95: call: cannam@95: cannam@95:
void fftw_plan_with_nthreads(int nthreads); cannam@95:cannam@95:
cannam@95: The nthreads argument indicates the number of threads you want
cannam@95: FFTW to use (or actually, the maximum number). All plans subsequently
cannam@95: created with any planner routine will use that many threads. You can
cannam@95: call fftw_plan_with_nthreads, create some plans, call
cannam@95: fftw_plan_with_nthreads again with a different argument, and
cannam@95: create some more plans for a new number of threads. Plans already created
cannam@95: before a call to fftw_plan_with_nthreads are unaffected. If you
cannam@95: pass an nthreads argument of 1 (the default), threads are
cannam@95: disabled for subsequent plans.
cannam@95:
cannam@95:
With OpenMP, to configure FFTW to use all of the currently running
cannam@95: OpenMP threads (set by omp_set_num_threads(nthreads) or by the
cannam@95: OMP_NUM_THREADS environment variable), you can do:
cannam@95: fftw_plan_with_nthreads(omp_get_max_threads()). (The ‘omp_’
cannam@95: OpenMP functions are declared via #include <omp.h>.)
cannam@95:
cannam@95:
Given a plan, you then execute it as usual with
cannam@95: fftw_execute(plan), and the execution will use the number of
cannam@95: threads specified when the plan was created. When done, you destroy
cannam@95: it as usual with fftw_destroy_plan. As described in
cannam@95: Thread safety, plan execution is thread-safe, but plan
cannam@95: creation and destruction are not: you should create/destroy
cannam@95: plans only from a single thread, but can safely execute multiple plans
cannam@95: in parallel.
cannam@95:
cannam@95:
There is one additional routine: if you want to get rid of all memory cannam@95: and other resources allocated internally by FFTW, you can call: cannam@95: cannam@95:
void fftw_cleanup_threads(void); cannam@95:cannam@95:
cannam@95: which is much like the fftw_cleanup() function except that it
cannam@95: also gets rid of threads-related data. You must not execute any
cannam@95: previously created plans after calling this function.
cannam@95:
cannam@95:
We should also mention one other restriction: if you save wisdom from a
cannam@95: program using the multi-threaded FFTW, that wisdom cannot be used
cannam@95: by a program using only the single-threaded FFTW (i.e. not calling
cannam@95: fftw_init_threads). See Words of Wisdom-Saving Plans.
cannam@95:
cannam@95:
cannam@95:
cannam@95: