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