Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.5/doc/html/Usage-of-Multi_002dthreaded-FFTW.html @ 127:7867fa7e1b6b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Current fftw source
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 18 Oct 2016 13:40:26 +0100
parents
children
comparison
equal deleted inserted replaced
126:4a7071416412 127:7867fa7e1b6b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- This manual is for FFTW
4 (version 3.3.5, 30 July 2016).
5
6 Copyright (C) 2003 Matteo Frigo.
7
8 Copyright (C) 2003 Massachusetts Institute of Technology.
9
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
13
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
18
19 Permission is granted to copy and distribute translations of this manual
20 into another language, under the above conditions for modified versions,
21 except that this permission notice may be stated in a translation
22 approved by the Free Software Foundation. -->
23 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
24 <head>
25 <title>FFTW 3.3.5: Usage of Multi-threaded FFTW</title>
26
27 <meta name="description" content="FFTW 3.3.5: Usage of Multi-threaded FFTW">
28 <meta name="keywords" content="FFTW 3.3.5: Usage of Multi-threaded FFTW">
29 <meta name="resource-type" content="document">
30 <meta name="distribution" content="global">
31 <meta name="Generator" content="makeinfo">
32 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
33 <link href="index.html#Top" rel="start" title="Top">
34 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
35 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
36 <link href="Multi_002dthreaded-FFTW.html#Multi_002dthreaded-FFTW" rel="up" title="Multi-threaded FFTW">
37 <link href="How-Many-Threads-to-Use_003f.html#How-Many-Threads-to-Use_003f" rel="next" title="How Many Threads to Use?">
38 <link href="Installation-and-Supported-Hardware_002fSoftware.html#Installation-and-Supported-Hardware_002fSoftware" rel="prev" title="Installation and Supported Hardware/Software">
39 <style type="text/css">
40 <!--
41 a.summary-letter {text-decoration: none}
42 blockquote.smallquotation {font-size: smaller}
43 div.display {margin-left: 3.2em}
44 div.example {margin-left: 3.2em}
45 div.indentedblock {margin-left: 3.2em}
46 div.lisp {margin-left: 3.2em}
47 div.smalldisplay {margin-left: 3.2em}
48 div.smallexample {margin-left: 3.2em}
49 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
50 div.smalllisp {margin-left: 3.2em}
51 kbd {font-style:oblique}
52 pre.display {font-family: inherit}
53 pre.format {font-family: inherit}
54 pre.menu-comment {font-family: serif}
55 pre.menu-preformatted {font-family: serif}
56 pre.smalldisplay {font-family: inherit; font-size: smaller}
57 pre.smallexample {font-size: smaller}
58 pre.smallformat {font-family: inherit; font-size: smaller}
59 pre.smalllisp {font-size: smaller}
60 span.nocodebreak {white-space:nowrap}
61 span.nolinebreak {white-space:nowrap}
62 span.roman {font-family:serif; font-weight:normal}
63 span.sansserif {font-family:sans-serif; font-weight:normal}
64 ul.no-bullet {list-style: none}
65 -->
66 </style>
67
68
69 </head>
70
71 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
72 <a name="Usage-of-Multi_002dthreaded-FFTW"></a>
73 <div class="header">
74 <p>
75 Next: <a href="How-Many-Threads-to-Use_003f.html#How-Many-Threads-to-Use_003f" accesskey="n" rel="next">How Many Threads to Use?</a>, Previous: <a href="Installation-and-Supported-Hardware_002fSoftware.html#Installation-and-Supported-Hardware_002fSoftware" accesskey="p" rel="prev">Installation and Supported Hardware/Software</a>, Up: <a href="Multi_002dthreaded-FFTW.html#Multi_002dthreaded-FFTW" accesskey="u" rel="up">Multi-threaded FFTW</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
76 </div>
77 <hr>
78 <a name="Usage-of-Multi_002dthreaded-FFTW-1"></a>
79 <h3 class="section">5.2 Usage of Multi-threaded FFTW</h3>
80
81 <p>Here, it is assumed that the reader is already familiar with the usage
82 of the uniprocessor FFTW routines, described elsewhere in this manual.
83 We only describe what one has to change in order to use the
84 multi-threaded routines.
85 </p>
86 <a name="index-OpenMP-1"></a>
87 <p>First, programs using the parallel complex transforms should be linked
88 with <code>-lfftw3_threads -lfftw3 -lm</code> on Unix, or <code>-lfftw3_omp
89 -lfftw3 -lm</code> if you compiled with OpenMP. You will also need to link
90 with whatever library is responsible for threads on your system
91 (e.g. <code>-lpthread</code> on GNU/Linux) or include whatever compiler flag
92 enables OpenMP (e.g. <code>-fopenmp</code> with gcc).
93 <a name="index-linking-on-Unix"></a>
94 </p>
95
96 <p>Second, before calling <em>any</em> FFTW routines, you should call the
97 function:
98 </p>
99 <div class="example">
100 <pre class="example">int fftw_init_threads(void);
101 </pre></div>
102 <a name="index-fftw_005finit_005fthreads"></a>
103
104 <p>This function, which need only be called once, performs any one-time
105 initialization required to use threads on your system. It returns zero
106 if there was some error (which should not happen under normal
107 circumstances) and a non-zero value otherwise.
108 </p>
109 <p>Third, before creating a plan that you want to parallelize, you should
110 call:
111 </p>
112 <div class="example">
113 <pre class="example">void fftw_plan_with_nthreads(int nthreads);
114 </pre></div>
115 <a name="index-fftw_005fplan_005fwith_005fnthreads"></a>
116
117 <p>The <code>nthreads</code> argument indicates the number of threads you want
118 FFTW to use (or actually, the maximum number). All plans subsequently
119 created with any planner routine will use that many threads. You can
120 call <code>fftw_plan_with_nthreads</code>, create some plans, call
121 <code>fftw_plan_with_nthreads</code> again with a different argument, and
122 create some more plans for a new number of threads. Plans already created
123 before a call to <code>fftw_plan_with_nthreads</code> are unaffected. If you
124 pass an <code>nthreads</code> argument of <code>1</code> (the default), threads are
125 disabled for subsequent plans.
126 </p>
127 <a name="index-OpenMP-2"></a>
128 <p>With OpenMP, to configure FFTW to use all of the currently running
129 OpenMP threads (set by <code>omp_set_num_threads(nthreads)</code> or by the
130 <code>OMP_NUM_THREADS</code> environment variable), you can do:
131 <code>fftw_plan_with_nthreads(omp_get_max_threads())</code>. (The &lsquo;<samp>omp_</samp>&rsquo;
132 OpenMP functions are declared via <code>#include &lt;omp.h&gt;</code>.)
133 </p>
134 <a name="index-thread-safety"></a>
135 <p>Given a plan, you then execute it as usual with
136 <code>fftw_execute(plan)</code>, and the execution will use the number of
137 threads specified when the plan was created. When done, you destroy
138 it as usual with <code>fftw_destroy_plan</code>. As described in
139 <a href="Thread-safety.html#Thread-safety">Thread safety</a>, plan <em>execution</em> is thread-safe, but plan
140 creation and destruction are <em>not</em>: you should create/destroy
141 plans only from a single thread, but can safely execute multiple plans
142 in parallel.
143 </p>
144 <p>There is one additional routine: if you want to get rid of all memory
145 and other resources allocated internally by FFTW, you can call:
146 </p>
147 <div class="example">
148 <pre class="example">void fftw_cleanup_threads(void);
149 </pre></div>
150 <a name="index-fftw_005fcleanup_005fthreads"></a>
151
152 <p>which is much like the <code>fftw_cleanup()</code> function except that it
153 also gets rid of threads-related data. You must <em>not</em> execute any
154 previously created plans after calling this function.
155 </p>
156 <p>We should also mention one other restriction: if you save wisdom from a
157 program using the multi-threaded FFTW, that wisdom <em>cannot be used</em>
158 by a program using only the single-threaded FFTW (i.e. not calling
159 <code>fftw_init_threads</code>). See <a href="Words-of-Wisdom_002dSaving-Plans.html#Words-of-Wisdom_002dSaving-Plans">Words of Wisdom-Saving Plans</a>.
160 </p>
161 <hr>
162 <div class="header">
163 <p>
164 Next: <a href="How-Many-Threads-to-Use_003f.html#How-Many-Threads-to-Use_003f" accesskey="n" rel="next">How Many Threads to Use?</a>, Previous: <a href="Installation-and-Supported-Hardware_002fSoftware.html#Installation-and-Supported-Hardware_002fSoftware" accesskey="p" rel="prev">Installation and Supported Hardware/Software</a>, Up: <a href="Multi_002dthreaded-FFTW.html#Multi_002dthreaded-FFTW" accesskey="u" rel="up">Multi-threaded FFTW</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
165 </div>
166
167
168
169 </body>
170 </html>