-
-
Notifications
You must be signed in to change notification settings - Fork 224
Expand file tree
/
Copy pathconcurrent.futures.html
More file actions
957 lines (866 loc) · 107 KB
/
concurrent.futures.html
File metadata and controls
957 lines (866 loc) · 107 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
<!DOCTYPE html>
<html lang="zh-TW" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>concurrent.futures --- 啟動平行任務 — Python 3.14.5 說明文件</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
<script src="../_static/documentation_options.js?v=8c54008b"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/translations.js?v=cbf116e0"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.14.5 說明文件 中搜尋"
href="../_static/opensearch.xml"/>
<link rel="author" title="關於這些文件" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜尋" href="../search.html" />
<link rel="copyright" title="版權所有" href="../copyright.html" />
<link rel="next" title="concurrent.interpreters --- 在同一個行程中使用多個直譯器" href="concurrent.interpreters.html" />
<link rel="prev" title="concurrent 套件" href="concurrent.html" />
<link rel="canonical" href="https://docs.python.org/3/library/concurrent.futures.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="選單">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="快速搜索" aria-label="快速搜索" type="search" name="q">
<input type="submit" value="前往">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
主題
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>自動</option>
<option value="light">淺色模式</option>
<option value="dark">深色模式</option>
</select>
</label>
<div>
<h3><a href="../contents.html">目錄</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> --- 啟動平行任務</a><ul>
<li><a class="reference internal" href="#executor-objects">Executor 物件</a></li>
<li><a class="reference internal" href="#threadpoolexecutor">ThreadPoolExecutor</a><ul>
<li><a class="reference internal" href="#threadpoolexecutor-example">ThreadPoolExecutor 範例</a></li>
</ul>
</li>
<li><a class="reference internal" href="#interpreterpoolexecutor">InterpreterPoolExecutor</a></li>
<li><a class="reference internal" href="#processpoolexecutor">ProcessPoolExecutor</a><ul>
<li><a class="reference internal" href="#processpoolexecutor-example">ProcessPoolExecutor 範例</a></li>
</ul>
</li>
<li><a class="reference internal" href="#future-objects">Future 物件</a></li>
<li><a class="reference internal" href="#module-functions">模組函式</a></li>
<li><a class="reference internal" href="#exception-classes">例外類別</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>上個主題</h4>
<p class="topless"><a href="concurrent.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent</span></code> 套件</a></p>
</div>
<div>
<h4>下個主題</h4>
<p class="topless"><a href="concurrent.interpreters.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.interpreters</span></code> --- 在同一個行程中使用多個直譯器</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/concurrent.futures.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>此頁面</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">回報錯誤</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">改進此頁面</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/concurrent.futures.rst?plain=1"
rel="nofollow">顯示原始碼
</a>
</li>
<li>
<a href="https://github.com/python/python-docs-zh-TW/blob/3.14/library/concurrent.futures.po?plain=1"
rel="nofollow">顯示翻譯原始碼</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>導航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="總索引"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="concurrent.interpreters.html" title="concurrent.interpreters --- 在同一個行程中使用多個直譯器"
accesskey="N">下一頁</a> |</li>
<li class="right" >
<a href="concurrent.html" title="concurrent 套件"
accesskey="P">上一頁</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.14.5 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 標準函式庫 (Standard Library)</a> »</li>
<li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">並行執行 (Concurrent Execution)</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> --- 啟動平行任務</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="search" name="q" id="search-box">
<input type="submit" value="前往">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
主題
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>自動</option>
<option value="light">淺色模式</option>
<option value="dark">深色模式</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-concurrent.futures">
<span id="concurrent-futures-launching-parallel-tasks"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> --- 啟動平行任務<a class="headerlink" href="#module-concurrent.futures" title="連結到這個標頭">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">在 3.2 版被加入.</span></p>
</div>
<p><strong>原始碼：</strong><a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/thread.py">Lib/concurrent/futures/thread.py</a>、<a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/process.py">Lib/concurrent/futures/process.py</a> 與 <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/interpreter.py">Lib/concurrent/futures/interpreter.py</a></p>
<hr class="docutils" />
<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> 模組提供了一個高階介面來非同步地 (asynchronously) 執行可呼叫物件 (callable) 。</p>
<p>非同步執行可以透過 <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> 或 <a class="reference internal" href="#concurrent.futures.InterpreterPoolExecutor" title="concurrent.futures.InterpreterPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">InterpreterPoolExecutor</span></code></a> 來使用執行緒 (thread) 執行，或透過 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 來使用單獨行程 (process) 執行。兩者都實作了相同的介面，該介面由抽象的 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 類別定義。</p>
<p><a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.Future</span></code></a> must not be confused with
<a class="reference internal" href="asyncio-future.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.Future</span></code></a>, which is designed for use with <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a>
tasks and coroutines. See the <a class="reference internal" href="asyncio-future.html"><span class="doc">asyncio's Future</span></a>
documentation for a detailed comparison of the two.</p>
<div class="availability docutils container">
<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">可用性</span></a>: not WASI.</p>
<p>此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly 平台</span></a>。</p>
</div>
<section id="executor-objects">
<h2>Executor 物件<a class="headerlink" href="#executor-objects" title="連結到這個標頭">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="concurrent.futures.Executor">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">Executor</span></span><a class="headerlink" href="#concurrent.futures.Executor" title="連結到這個定義">¶</a></dt>
<dd><p>提供非同步執行呼叫方法的抽象類別。不應直接使用它，而應透過其具體子類別來使用。</p>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Executor.submit">
<span class="sig-name descname"><span class="pre">submit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.submit" title="連結到這個定義">¶</a></dt>
<dd><p>為可呼叫物件 <em>fn</em> 排程來以 <code class="docutils literal notranslate"><span class="pre">fn(*args,</span> <span class="pre">**kwargs)</span></code> 的形式執行並回傳一個表示可呼叫的執行的 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 物件。</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>
<span class="n">future</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="mi">323</span><span class="p">,</span> <span class="mi">1235</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">future</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>
</pre></div>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Executor.map">
<span class="sig-name descname"><span class="pre">map</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">iterables</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">chunksize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffersize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.map" title="連結到這個定義">¶</a></dt>
<dd><p>類似於 <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map(fn,</span> <span class="pre">*iterables)</span></code></a>，除了：</p>
<ul class="simple">
<li><p>The <em>iterables</em> are collected immediately rather than lazily, unless a
<em>buffersize</em> is specified to limit the number of submitted tasks whose
results have not yet been yielded. If the buffer is full, iteration over
the <em>iterables</em> pauses until a result is yielded from the buffer.</p></li>
<li><p><em>fn</em> 是非同步執行的，並且對 <em>fn</em> 的多次呼叫可以並行處理。</p></li>
</ul>
<p>如果 <a class="reference internal" href="stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> 被呼叫，且在原先呼叫 <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.map()</span></code></a> 的 <em>timeout</em> 秒後結果仍不可用，回傳的疊代器就會引發 <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>。<em>timeout</em> 可以是整數或浮點數。如果未指定 <em>timeout</em> 或為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則等待時間就不會有限制。</p>
<p>如果 <em>fn</em> 呼叫引發例外，則當從疊代器中檢索到它的值時將引發該例外。</p>
<p>使用 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 時，此方法將 <em>iterables</em> 分成許多分塊 (chunks)，並將其作為獨立的任務來提交給池 (pool)。可以透過將 <em>chunksize</em> 設定為正整數來指定這些分塊的（約略）大小。對於非常長的可疊代物件，<em>chunksize</em> 使用較大的值（與預設大小 1 相比）可以顯著提高性能。對於 <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> 和 <a class="reference internal" href="#concurrent.futures.InterpreterPoolExecutor" title="concurrent.futures.InterpreterPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">InterpreterPoolExecutor</span></code></a>，<em>chunksize</em> 無效。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.5 版的變更: </span>新增 <em>chunksize</em> 參數。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.14 版的變更: </span>新增 <em>buffersize</em> 參數。</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Executor.shutdown">
<span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">cancel_futures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.shutdown" title="連結到這個定義">¶</a></dt>
<dd><p>向 executor 發出訊號 (signal)，表明它應該在目前未定 (pending) 的 future 完成執行時釋放它正在使用的任何資源。在關閉後呼叫 <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a> 和 <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.map()</span></code></a> 將引發 <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>。</p>
<p>如果 <em>wait</em> 為 <code class="docutils literal notranslate"><span class="pre">True</span></code> 則此方法將不會回傳，直到所有未定的 futures 完成執行並且與 executor 關聯的資源都被釋放。如果 <em>wait</em> 為 <code class="docutils literal notranslate"><span class="pre">False</span></code> 則此方法將立即回傳，並且當所有未定的 future 執行完畢時，與 executor 關聯的資源將被釋放。不管 <em>wait</em> 的值如何，整個 Python 程式都不會退出，直到所有未定的 futures 執行完畢。</p>
<p>如果 <em>cancel_futures</em> 為 <code class="docutils literal notranslate"><span class="pre">True</span></code>，此方法將取消 executor 尚未開始運行的所有未定 future。無論 <em>cancel_futures</em> 的值如何，任何已完成或正在運行的 future 都不會被取消。</p>
<p>如果 <em>cancel_futures</em> 和 <em>wait</em> 都為 <code class="docutils literal notranslate"><span class="pre">True</span></code>，則 executor 已開始運行的所有 future 將在此方法回傳之前完成。剩餘的 future 被取消。</p>
<p>如果使用 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 陳述式來將 executor 用作 <a class="reference internal" href="../glossary.html#term-context-manager"><span class="xref std std-term">context manager</span></a>，那你就可以不用明確地呼叫此方法，這將會自己關閉 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a>（如同呼叫 <a class="reference internal" href="#concurrent.futures.Executor.shutdown" title="concurrent.futures.Executor.shutdown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.shutdown()</span></code></a> 時 <em>wait</em> 被設定為 <code class="docutils literal notranslate"><span class="pre">True</span></code> 般等待）：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">shutil</span>
<span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">'src1.txt'</span><span class="p">,</span> <span class="s1">'dest1.txt'</span><span class="p">)</span>
<span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">'src2.txt'</span><span class="p">,</span> <span class="s1">'dest2.txt'</span><span class="p">)</span>
<span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">'src3.txt'</span><span class="p">,</span> <span class="s1">'dest3.txt'</span><span class="p">)</span>
<span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">'src4.txt'</span><span class="p">,</span> <span class="s1">'dest4.txt'</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.9 版的變更: </span>新增 <em>cancel_futures</em>。</p>
</div>
</dd></dl>
</dd></dl>
</section>
<section id="threadpoolexecutor">
<h2>ThreadPoolExecutor<a class="headerlink" href="#threadpoolexecutor" title="連結到這個標頭">¶</a></h2>
<p><a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> 是一個 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 子類別，它使用執行緒池來非同步地執行呼叫。</p>
<p>當與 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 關聯的可呼叫物件等待另一個 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 的結果時，可能會發生死鎖 (deadlock)。例如：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">time</span>
<span class="k">def</span><span class="w"> </span><span class="nf">wait_on_b</span><span class="p">():</span>
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">b</span><span class="o">.</span><span class="n">result</span><span class="p">())</span> <span class="c1"># b 永遠不會完成，因為它正在等待 a。</span>
<span class="k">return</span> <span class="mi">5</span>
<span class="k">def</span><span class="w"> </span><span class="nf">wait_on_a</span><span class="p">():</span>
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">result</span><span class="p">())</span> <span class="c1"># a 永遠不會完成，因為它正在等待 b。</span>
<span class="k">return</span> <span class="mi">6</span>
<span class="n">executor</span> <span class="o">=</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_b</span><span class="p">)</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_a</span><span class="p">)</span>
</pre></div>
</div>
<p>和：</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">wait_on_future</span><span class="p">():</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="c1"># 這將永遠不會完成，因為只有一個工作執行緒且</span>
<span class="c1"># 它正在執行這個函式。</span>
<span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>
<span class="n">executor</span> <span class="o">=</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">future</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_future</span><span class="p">)</span>
<span class="c1"># 注意：呼叫 future.result() 也會造成死鎖 (deadlock)，因為</span>
<span class="c1"># 唯一的工作執行緒已經在等待 wait_on_future()。</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="concurrent.futures.ThreadPoolExecutor">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ThreadPoolExecutor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">max_workers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">thread_name_prefix</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initializer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.ThreadPoolExecutor" title="連結到這個定義">¶</a></dt>
<dd><p>一個 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 子類別，它使用最多有 <em>max_workers</em> 個執行緒的池來非同步地執行呼叫。</p>
<p>所有排隊到 <code class="docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code> 的執行緒都將在直譯器退出之前加入。請注意，執行此操作的退出處理程式會在任何使用 <code class="docutils literal notranslate"><span class="pre">atexit</span></code> 新增的退出處理程式<em>之前</em>執行。這意味著必須捕獲並處理主執行緒中的例外，以便向執行緒發出訊號來正常退出 (gracefully exit)。因此，建議不要將 <code class="docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code> 用於長時間運行的任務。</p>
<p><em>initializer</em> 是一個可選的可呼叫物件，在每個工作執行緒開始時呼叫； <em>initargs</em> 是傳遞給 initializer 的引數元組 (tuple)。如果 <em>initializer</em> 引發例外，所有目前未定的作業以及任何向池中提交 (submit) 更多作業的嘗試都將引發 <a class="reference internal" href="#concurrent.futures.thread.BrokenThreadPool" title="concurrent.futures.thread.BrokenThreadPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenThreadPool</span></code></a>。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.5 版的變更: </span>如果 <em>max_workers</em> 為 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或未給定，它將預設為機器上的處理器數量乘以 <code class="docutils literal notranslate"><span class="pre">5</span></code>，這假定了 <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> 通常用於 I/O 重疊而非 CPU 密集的作業，並且 worker 的數量應該高於 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 的 worker 數量。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.6 版的變更: </span>新增 <em>thread_name_prefix</em> 參數以允許使用者控制由池所建立的工作執行緒 (worker thread) 的 <a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a> 名稱，以便於除錯。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.7 版的變更: </span>新增 <em>initializer</em> 與 <em>initargs</em> 引數。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8 版的變更: </span><em>max_workers</em> 的預設值改為 <code class="docutils literal notranslate"><span class="pre">min(32,</span> <span class="pre">os.cpu_count()</span> <span class="pre">+</span> <span class="pre">4)</span></code>。此預設值為 I/O 密集任務至少保留了 5 個 worker。它最多使用 32 個 CPU 核心來執行CPU 密集任務，以釋放 GIL。並且它避免了在多核機器上隱晦地使用非常大量的資源。</p>
<p>ThreadPoolExecutor 現在在啟動 <em>max_workers</em> 工作執行緒之前會重用 (reuse) 空閒的工作執行緒。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.13 版的變更: </span><em>max_workers</em> 的預設值被改為 <code class="docutils literal notranslate"><span class="pre">min(32,</span> <span class="pre">(os.process_cpu_count()</span> <span class="pre">or</span> <span class="pre">1)</span> <span class="pre">+</span> <span class="pre">4)</span></code>。</p>
</div>
</dd></dl>
<section id="threadpoolexecutor-example">
<span id="id1"></span><h3>ThreadPoolExecutor 範例<a class="headerlink" href="#threadpoolexecutor-example" title="連結到這個標頭">¶</a></h3>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">concurrent.futures</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">urllib.request</span>
<span class="n">URLS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'http://www.foxnews.com/'</span><span class="p">,</span>
<span class="s1">'http://www.cnn.com/'</span><span class="p">,</span>
<span class="s1">'http://europe.wsj.com/'</span><span class="p">,</span>
<span class="s1">'http://www.bbc.co.uk/'</span><span class="p">,</span>
<span class="s1">'http://nonexistent-subdomain.python.org/'</span><span class="p">]</span>
<span class="c1"># Retrieve a single page and report the URL and contents</span>
<span class="k">def</span><span class="w"> </span><span class="nf">load_url</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">timeout</span><span class="p">):</span>
<span class="k">with</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">urlopen</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="n">timeout</span><span class="p">)</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="k">return</span> <span class="n">conn</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="c1"># We can use a with statement to ensure threads are cleaned up promptly</span>
<span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>
<span class="c1"># Start the load operations and mark each future with its URL</span>
<span class="n">future_to_url</span> <span class="o">=</span> <span class="p">{</span><span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">load_url</span><span class="p">,</span> <span class="n">url</span><span class="p">,</span> <span class="mi">60</span><span class="p">):</span> <span class="n">url</span> <span class="k">for</span> <span class="n">url</span> <span class="ow">in</span> <span class="n">URLS</span><span class="p">}</span>
<span class="k">for</span> <span class="n">future</span> <span class="ow">in</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">as_completed</span><span class="p">(</span><span class="n">future_to_url</span><span class="p">):</span>
<span class="n">url</span> <span class="o">=</span> <span class="n">future_to_url</span><span class="p">[</span><span class="n">future</span><span class="p">]</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">future</span><span class="o">.</span><span class="n">result</span><span class="p">()</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%r</span><span class="s1"> generated an exception: </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">exc</span><span class="p">))</span>
<span class="k">else</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%r</span><span class="s1"> page is </span><span class="si">%d</span><span class="s1"> bytes'</span> <span class="o">%</span> <span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)))</span>
</pre></div>
</div>
</section>
</section>
<section id="interpreterpoolexecutor">
<h2>InterpreterPoolExecutor<a class="headerlink" href="#interpreterpoolexecutor" title="連結到這個標頭">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified added">在 3.14 版被加入.</span></p>
</div>
<p>The <a class="reference internal" href="#concurrent.futures.InterpreterPoolExecutor" title="concurrent.futures.InterpreterPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">InterpreterPoolExecutor</span></code></a> class uses a pool of interpreters
to execute calls asynchronously. It is a <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>
subclass, which means each worker is running in its own thread.
The difference here is that each worker has its own interpreter,
and runs each task using that interpreter.</p>
<p>The biggest benefit to using interpreters instead of only threads
is true multi-core parallelism. Each interpreter has its own
<a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a>, so code
running in one interpreter can run on one CPU core, while code in
another interpreter runs unblocked on a different core.</p>
<p>The tradeoff is that writing concurrent code for use with multiple
interpreters can take extra effort. However, this is because it
forces you to be deliberate about how and when interpreters interact,
and to be explicit about what data is shared between interpreters.
This results in several benefits that help balance the extra effort,
including true multi-core parallelism, For example, code written
this way can make it easier to reason about concurrency. Another
major benefit is that you don't have to deal with several of the
big pain points of using threads, like race conditions.</p>
<p>Each worker's interpreter is isolated from all the other interpreters.
"Isolated" means each interpreter has its own runtime state and
operates completely independently. For example, if you redirect
<a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> in one interpreter, it will not be automatically
redirected to any other interpreter. If you import a module in one
interpreter, it is not automatically imported in any other. You
would need to import the module separately in interpreter where
you need it. In fact, each module imported in an interpreter is
a completely separate object from the same module in a different
interpreter, including <a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a>, <a class="reference internal" href="builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a>,
and even <code class="docutils literal notranslate"><span class="pre">__main__</span></code>.</p>
<p>Isolation means a mutable object, or other data, cannot be used
by more than one interpreter at the same time. That effectively means
interpreters cannot actually share such objects or data. Instead,
each interpreter must have its own copy, and you will have to
synchronize any changes between the copies manually. Immutable
objects and data, like the builtin singletons, strings, and tuples
of immutable objects, don't have these limitations.</p>
<p>Communicating and synchronizing between interpreters is most effectively
done using dedicated tools, like those proposed in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0734/"><strong>PEP 734</strong></a>. One less
efficient alternative is to serialize with <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a> and then send
the bytes over a shared <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> or
<a class="reference internal" href="os.html#os.pipe" title="os.pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">pipe</span></code></a>.</p>
<dl class="py class">
<dt class="sig sig-object py" id="concurrent.futures.InterpreterPoolExecutor">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">InterpreterPoolExecutor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">max_workers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">thread_name_prefix</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initializer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.InterpreterPoolExecutor" title="連結到這個定義">¶</a></dt>
<dd><p>A <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> subclass that executes calls asynchronously
using a pool of at most <em>max_workers</em> threads. Each thread runs
tasks in its own interpreter. The worker interpreters are isolated
from each other, which means each has its own runtime state and that
they can't share any mutable objects or other data. Each interpreter
has its own <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a>,
which means code run with this executor has true multi-core parallelism.</p>
<p>The optional <em>initializer</em> and <em>initargs</em> arguments have the same
meaning as for <code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code>: the initializer is run
when each worker is created, though in this case it is run in
the worker's interpreter. The executor serializes the <em>initializer</em>
and <em>initargs</em> using <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a> when sending them to the worker's
interpreter.</p>
<div class="admonition note">
<p class="admonition-title">備註</p>
<p>The executor may replace uncaught exceptions from <em>initializer</em>
with <a class="reference internal" href="concurrent.interpreters.html#concurrent.interpreters.ExecutionFailed" title="concurrent.interpreters.ExecutionFailed"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionFailed</span></code></a>.</p>
</div>
<p>Other caveats from parent <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> apply here.</p>
</dd></dl>
<p><a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">submit()</span></code></a> and <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">map()</span></code></a> work like normal,
except the worker serializes the callable and arguments using
<a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a> when sending them to its interpreter. The worker
likewise serializes the return value when sending it back.</p>
<p>When a worker's current task raises an uncaught exception, the worker
always tries to preserve the exception as-is. If that is successful
then it also sets the <code class="docutils literal notranslate"><span class="pre">__cause__</span></code> to a corresponding
<a class="reference internal" href="concurrent.interpreters.html#concurrent.interpreters.ExecutionFailed" title="concurrent.interpreters.ExecutionFailed"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionFailed</span></code></a>
instance, which contains a summary of the original exception.
In the uncommon case that the worker is not able to preserve the
original as-is then it directly preserves the corresponding
<a class="reference internal" href="concurrent.interpreters.html#concurrent.interpreters.ExecutionFailed" title="concurrent.interpreters.ExecutionFailed"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionFailed</span></code></a>
instance instead.</p>
</section>
<section id="processpoolexecutor">
<h2>ProcessPoolExecutor<a class="headerlink" href="#processpoolexecutor" title="連結到這個標頭">¶</a></h2>
<p><a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 類別是一個 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 的子類別，它使用行程池來非同步地執行呼叫。<a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 使用了 <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> 模組，這允許它避開<a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">全域直譯器鎖 (Global Interpreter Lock)</span></a>，但也意味著只能執行和回傳可被 pickle 的 (picklable) 物件。</p>
<p><code class="docutils literal notranslate"><span class="pre">__main__</span></code> 模組必須可以被工作子行程 (worker subprocess) 引入。這意味著 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 將無法在交互式直譯器 (interactive interpreter) 中工作。</p>
<p>從提交給 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 的可呼叫物件中呼叫 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 或 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 方法將導致死鎖。</p>
<p>Note that the restrictions on functions and arguments needing to picklable as
per <a class="reference internal" href="multiprocessing.html#multiprocessing.Process" title="multiprocessing.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">multiprocessing.Process</span></code></a> apply when using <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">submit()</span></code></a>
and <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">map()</span></code></a> on a <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>. A function defined
in a REPL or a lambda should not be expected to work.</p>
<dl class="py class">
<dt class="sig sig-object py" id="concurrent.futures.ProcessPoolExecutor">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ProcessPoolExecutor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">max_workers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mp_context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initializer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">initargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_tasks_per_child</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.ProcessPoolExecutor" title="連結到這個定義">¶</a></dt>
<dd><p>一個 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 子類別，它使用了最多有 <em>max_workers</em> 個行程的池來非同步地執行呼叫。如果 <em>max_workers</em> 為 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或未給定，它將被預設為 <a class="reference internal" href="os.html#os.process_cpu_count" title="os.process_cpu_count"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.process_cpu_count()</span></code></a>。如果 <em>max_workers</em> 小於或等於 <code class="docutils literal notranslate"><span class="pre">0</span></code>，則會引發 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>。在 Windows 上，<em>max_workers</em> 必須小於或等於 <code class="docutils literal notranslate"><span class="pre">61</span></code>。如果不是，則會引發 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>。如果 <em>max_workers</em> 為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則預設選擇最多為 <code class="docutils literal notranslate"><span class="pre">61</span></code>，即便有更多處理器可用。<em>mp_context</em> 可以是 <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> 情境 (context) 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>。它將用於啟動 worker。如果 <em>mp_context</em> 為 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或未給定，則使用預設的 <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> 情境。請見 <a class="reference internal" href="multiprocessing.html#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>。</p>
<p><em>initializer</em> 是一個可選的可呼叫物件，在每個工作行程 (worker process) 開始時呼叫；<em>initargs</em> 是傳遞給 initializer 的引數元組。如果 <em>initializer</em> 引發例外，所有目前未定的作業以及任何向池中提交更多作業的嘗試都將引發 <a class="reference internal" href="#concurrent.futures.process.BrokenProcessPool" title="concurrent.futures.process.BrokenProcessPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenProcessPool</span></code></a>。</p>
<p><em>max_tasks_per_child</em> 是一個可選引數，它指定單個行程在退出並被新的工作行程替換之前可以執行的最大任務數。預設情況下 <em>max_tasks_per_child</em> 是 <code class="docutils literal notranslate"><span class="pre">None</span></code>，這意味著工作行程的生命週期將與池一樣長。當指定最大值時，在沒有 <em>mp_context</em> 參數的情況下，將預設使用 "spawn" 做為 multiprocessing 啟動方法。此功能與 "fork" 啟動方法不相容。</p>
<div class="admonition note">
<p class="admonition-title">備註</p>
<p>Bugs have been reported when using the <em>max_tasks_per_child</em> feature that
can result in the <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> hanging in some
circumstances. Follow its eventual resolution in <a class="reference external" href="https://github.com/python/cpython/issues/115634">gh-115634</a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.3 版的變更: </span>當其中一個工作行程突然終止時，現在會引發 <a class="reference internal" href="#concurrent.futures.process.BrokenProcessPool" title="concurrent.futures.process.BrokenProcessPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenProcessPool</span></code></a> 錯誤。在過去，此行為是未定義的 (undefined)，但對 executor 或其 future 的操作經常會發生凍結或死鎖。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.7 版的變更: </span>新增了 <em>mp_context</em> 引數以允許使用者控制由池所建立的工作行程的 start_method。</p>
<p>新增 <em>initializer</em> 與 <em>initargs</em> 引數。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.11 版的變更: </span>新增了 <em>max_tasks_per_child</em> 引數以允許使用者控制池中 worker 的生命週期。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.12 版的變更: </span>在 POSIX 系統上，如果你的應用程式有多個執行緒並且 <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> 情境使用了 <code class="docutils literal notranslate"><span class="pre">"fork"</span></code> 啟動方法：內部呼叫以產生 worker 的 <a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> 函式可能會引發 <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>。傳遞一個 <em>mp_context</em> 以配置為使用不同的啟動方法。更多說明請參閱 <a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> 文件。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.13 版的變更: </span><em>max_workers</em> uses <a class="reference internal" href="os.html#os.process_cpu_count" title="os.process_cpu_count"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.process_cpu_count()</span></code></a> by default, instead of
<a class="reference internal" href="os.html#os.cpu_count" title="os.cpu_count"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.cpu_count()</span></code></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.14 版的變更: </span>The default process start method (see
<a class="reference internal" href="multiprocessing.html#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>) changed away from <em>fork</em>. If you
require the <em>fork</em> start method for <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> you must
explicitly pass <code class="docutils literal notranslate"><span class="pre">mp_context=multiprocessing.get_context("fork")</span></code>.</p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.ProcessPoolExecutor.terminate_workers">
<span class="sig-name descname"><span class="pre">terminate_workers</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.ProcessPoolExecutor.terminate_workers" title="連結到這個定義">¶</a></dt>
<dd><p>Attempt to terminate all living worker processes immediately by calling
<a class="reference internal" href="multiprocessing.html#multiprocessing.Process.terminate" title="multiprocessing.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Process.terminate</span></code></a> on each of them.
Internally, it will also call <a class="reference internal" href="#concurrent.futures.Executor.shutdown" title="concurrent.futures.Executor.shutdown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.shutdown()</span></code></a> to ensure that all
other resources associated with the executor are freed.</p>
<p>After calling this method the caller should no longer submit tasks to the
executor.</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.14 版被加入.</span></p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.ProcessPoolExecutor.kill_workers">
<span class="sig-name descname"><span class="pre">kill_workers</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.ProcessPoolExecutor.kill_workers" title="連結到這個定義">¶</a></dt>
<dd><p>Attempt to kill all living worker processes immediately by calling
<a class="reference internal" href="multiprocessing.html#multiprocessing.Process.kill" title="multiprocessing.Process.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Process.kill</span></code></a> on each of them.
Internally, it will also call <a class="reference internal" href="#concurrent.futures.Executor.shutdown" title="concurrent.futures.Executor.shutdown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.shutdown()</span></code></a> to ensure that all
other resources associated with the executor are freed.</p>
<p>After calling this method the caller should no longer submit tasks to the
executor.</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.14 版被加入.</span></p>
</div>
</dd></dl>
</dd></dl>
<section id="processpoolexecutor-example">
<span id="id2"></span><h3>ProcessPoolExecutor 範例<a class="headerlink" href="#processpoolexecutor-example" title="連結到這個標頭">¶</a></h3>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">concurrent.futures</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">math</span>
<span class="n">PRIMES</span> <span class="o">=</span> <span class="p">[</span>
<span class="mi">112272535095293</span><span class="p">,</span>
<span class="mi">112582705942171</span><span class="p">,</span>
<span class="mi">112272535095293</span><span class="p">,</span>
<span class="mi">115280095190773</span><span class="p">,</span>
<span class="mi">115797848077099</span><span class="p">,</span>
<span class="mi">1099726899285419</span><span class="p">]</span>
<span class="k">def</span><span class="w"> </span><span class="nf">is_prime</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
<span class="k">if</span> <span class="n">n</span> <span class="o"><</span> <span class="mi">2</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="n">sqrt_n</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">floor</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">n</span><span class="p">)))</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">sqrt_n</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">):</span>
<span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
<span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ProcessPoolExecutor</span><span class="p">()</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>
<span class="k">for</span> <span class="n">number</span><span class="p">,</span> <span class="n">prime</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">PRIMES</span><span class="p">,</span> <span class="n">executor</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">is_prime</span><span class="p">,</span> <span class="n">PRIMES</span><span class="p">)):</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%d</span><span class="s1"> is prime: </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">number</span><span class="p">,</span> <span class="n">prime</span><span class="p">))</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">main</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>
<section id="future-objects">
<h2>Future 物件<a class="headerlink" href="#future-objects" title="連結到這個標頭">¶</a></h2>
<p><a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 類別封裝了可呼叫物件的非同步執行。<a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 實例由 <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a> 建立。</p>
<dl class="py class">
<dt class="sig sig-object py" id="concurrent.futures.Future">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">Future</span></span><a class="headerlink" href="#concurrent.futures.Future" title="連結到這個定義">¶</a></dt>
<dd><p>封裝可呼叫物件的非同步執行。<a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 實例由 <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a> 建立，且除測試外不應直接建立。</p>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.cancel">
<span class="sig-name descname"><span class="pre">cancel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.cancel" title="連結到這個定義">¶</a></dt>
<dd><p>嘗試取消呼叫。如果呼叫目前正在執行或已完成運行且無法取消，則該方法將回傳 <code class="docutils literal notranslate"><span class="pre">False</span></code>，否則呼叫將被取消並且該方法將回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.cancelled">
<span class="sig-name descname"><span class="pre">cancelled</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.cancelled" title="連結到這個定義">¶</a></dt>
<dd><p>如果該呼叫成功被取消，則回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.running">
<span class="sig-name descname"><span class="pre">running</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.running" title="連結到這個定義">¶</a></dt>
<dd><p>如果呼叫正在執行且無法取消，則回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.done">
<span class="sig-name descname"><span class="pre">done</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.done" title="連結到這個定義">¶</a></dt>
<dd><p>如果呼叫成功被取消或結束運行，則回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.result">
<span class="sig-name descname"><span class="pre">result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.result" title="連結到這個定義">¶</a></dt>
<dd><p>回傳該呼叫回傳的值。如果呼叫尚未完成，則此方法將等待至多 <em>timeout</em> 秒。如果呼叫在 <em>timeout</em> 秒內未完成，則會引發 <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>。<em>timeout</em> 可以是整數或浮點數。如果未指定 <em>timeout</em> 或為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則等待時間就不會有限制。</p>
<p>如果 future 在完成之前被取消，那麼 <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a> 將被引發。</p>
<p>如果該呼叫引發了例外，此方法將引發相同的例外。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.exception">
<span class="sig-name descname"><span class="pre">exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.exception" title="連結到這個定義">¶</a></dt>
<dd><p>回傳該呼叫引發的例外。如果呼叫尚未完成，則此方法將等待至多 <em>timeout</em> 秒。如果呼叫在 <em>timeout</em> 秒內未完成，則會引發 <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>。 <em>timeout</em> 可以是整數或浮點數。如果未指定 <em>timeout</em> 或為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則等待時間就不會有限制。</p>
<p>如果 future 在完成之前被取消，那麼 <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a> 將被引發。</p>
<p>如果呼叫在沒有引發的情況下完成，則回傳 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.add_done_callback">
<span class="sig-name descname"><span class="pre">add_done_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.add_done_callback" title="連結到這個定義">¶</a></dt>
<dd><p>將可呼叫的 <em>fn</em> 附加到 future 上。當 future 被取消或完成運行時，<em>fn</em> 將被以 future 作為其唯一引數來呼叫。</p>
<p>新增的可呼叫物件按新增順序呼叫，並且始終在屬於新增它們的行程的執行緒中呼叫。如果可呼叫物件引發 <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a> 子類別，它將被記錄 (log) 並忽略。如果可呼叫物件引發 <a class="reference internal" href="exceptions.html#BaseException" title="BaseException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseException</span></code></a> 子類別，該行為未定義。</p>
<p>如果 future 已經完成或被取消，<em>fn</em> 將立即被呼叫。</p>
</dd></dl>
<p>以下 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 方法旨在用於單元測試和 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實作。</p>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.set_running_or_notify_cancel">
<span class="sig-name descname"><span class="pre">set_running_or_notify_cancel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_running_or_notify_cancel" title="連結到這個定義">¶</a></dt>
<dd><p>此方法只能在與 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 關聯的工作被執行之前於 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實作中呼叫，或者在單元測試中呼叫。</p>
<p>如果該方法回傳 <code class="docutils literal notranslate"><span class="pre">False</span></code> 則 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 已被取消，即 <a class="reference internal" href="#concurrent.futures.Future.cancel" title="concurrent.futures.Future.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.cancel()</span></code></a> 被呼叫並回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。任何等待 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 完成的執行緒（即透過 <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a> 或 <a class="reference internal" href="#concurrent.futures.wait" title="concurrent.futures.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait()</span></code></a>）將被喚醒。</p>
<p>如果該方法回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code> 則代表 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 未被取消並已進入運行狀態，意即呼叫 <a class="reference internal" href="#concurrent.futures.Future.running" title="concurrent.futures.Future.running"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.running()</span></code></a> 將回傳 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
<p>此方法只能呼叫一次，且不能在呼叫 <a class="reference internal" href="#concurrent.futures.Future.set_result" title="concurrent.futures.Future.set_result"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.set_result()</span></code></a> 或 <a class="reference internal" href="#concurrent.futures.Future.set_exception" title="concurrent.futures.Future.set_exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.set_exception()</span></code></a> 之後呼叫。</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.set_result">
<span class="sig-name descname"><span class="pre">set_result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">result</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_result" title="連結到這個定義">¶</a></dt>
<dd><p>將與 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 關聯的工作結果設定為 <em>result</em>。</p>
<p>此方法只能在 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實作中和單元測試中使用。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8 版的變更: </span>如果 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 已經完成，此方法會引發 <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">concurrent.futures.InvalidStateError</span></code></a>。</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="concurrent.futures.Future.set_exception">
<span class="sig-name descname"><span class="pre">set_exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exception</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_exception" title="連結到這個定義">¶</a></dt>
<dd><p>將與 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 關聯的工作結果設定為 <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></a> <em>exception</em>。</p>
<p>此方法只能在 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實作中和單元測試中使用。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.8 版的變更: </span>如果 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 已經完成，此方法會引發 <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">concurrent.futures.InvalidStateError</span></code></a>。</p>
</div>
</dd></dl>
</dd></dl>
</section>
<section id="module-functions">
<h2>模組函式<a class="headerlink" href="#module-functions" title="連結到這個標頭">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="concurrent.futures.wait">
<span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_when</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ALL_COMPLETED</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.wait" title="連結到這個定義">¶</a></dt>
<dd><p>等待 <em>fs</em> 給定的 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 實例（可能由不同的 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實例建立）完成。提供給 <em>fs</em> 的重複 future 將被刪除，並且只會回傳一次。回傳一個集合的附名二元組 (named 2-tuple of sets)。第一組名為 <code class="docutils literal notranslate"><span class="pre">done</span></code>，包含在等待完成之前完成的 future（已完成或被取消的 future）。第二組名為 <code class="docutils literal notranslate"><span class="pre">not_done</span></code>，包含未完成的 future（未定或運行中的 future）。</p>
<p><em>timeout</em> 可用於控制回傳前等待的最大秒數。<em>timeout</em> 可以是整數或浮點數。如果未指定 <em>timeout</em> 或為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則等待時間就沒有限制。</p>
<p><em>return_when</em> 表示此函式應回傳的時間。它必須是以下常數之一：</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>常數</p></th>
<th class="head"><p>描述</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><dl class="py data">
<dt class="sig sig-object py" id="concurrent.futures.FIRST_COMPLETED">
<span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">FIRST_COMPLETED</span></span><a class="headerlink" href="#concurrent.futures.FIRST_COMPLETED" title="連結到這個定義">¶</a></dt>
<dd></dd></dl>
</td>
<td><p>當任何 future 完成或被取消時，該函式就會回傳。</p></td>
</tr>
<tr class="row-odd"><td><dl class="py data">
<dt class="sig sig-object py" id="concurrent.futures.FIRST_EXCEPTION">
<span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">FIRST_EXCEPTION</span></span><a class="headerlink" href="#concurrent.futures.FIRST_EXCEPTION" title="連結到這個定義">¶</a></dt>
<dd></dd></dl>
</td>
<td><p>該函式會在任何 future 透過引發例外而完結時回傳。如果 future 沒有引發例外，那麼它等同於 <a class="reference internal" href="#concurrent.futures.ALL_COMPLETED" title="concurrent.futures.ALL_COMPLETED"><code class="xref py py-const docutils literal notranslate"><span class="pre">ALL_COMPLETED</span></code></a>。</p></td>
</tr>
<tr class="row-even"><td><dl class="py data">
<dt class="sig sig-object py" id="concurrent.futures.ALL_COMPLETED">
<span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ALL_COMPLETED</span></span><a class="headerlink" href="#concurrent.futures.ALL_COMPLETED" title="連結到這個定義">¶</a></dt>
<dd></dd></dl>
</td>
<td><p>當所有 future 都完成或被取消時，該函式才會回傳。</p></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="concurrent.futures.as_completed">
<span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">as_completed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.as_completed" title="連結到這個定義">¶</a></dt>
<dd><p>回傳由 <em>fs</em> 給定的 <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> 實例（可能由不同的 <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> 實例建立）的疊代器，它在完成時產生 future（已完成或被取消的 future）。<em>fs</em> 給定的任何重複的 future 將只被回傳一次。呼叫 <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a> 之前完成的任何 future 將首先產生。如果 <a class="reference internal" href="stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> 被呼叫，並且在原先呼叫 <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a> 的 <em>timeout</em> 秒後結果仍不可用，則回傳的疊代器會引發 <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>。<em>timeout</em> 可以是整數或浮點數。如果未指定 <em>timeout</em> 或為 <code class="docutils literal notranslate"><span class="pre">None</span></code>，則等待時間就沒有限制。</p>
</dd></dl>
<div class="admonition seealso">
<p class="admonition-title">也參考</p>
<dl class="simple">
<dt><span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-3148/"><strong>PEP 3148</strong></a> -- futures - 非同步地執行運算</dt><dd><p>描述此功能並提出被包含於 Python 標準函式庫中的提案。</p>
</dd>
</dl>
</div>
</section>
<section id="exception-classes">
<h2>例外類別<a class="headerlink" href="#exception-classes" title="連結到這個標頭">¶</a></h2>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.CancelledError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">CancelledError</span></span><a class="headerlink" href="#concurrent.futures.CancelledError" title="連結到這個定義">¶</a></dt>
<dd><p>當 future 被取消時引發。</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.TimeoutError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">TimeoutError</span></span><a class="headerlink" href="#concurrent.futures.TimeoutError" title="連結到這個定義">¶</a></dt>
<dd><p><a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> 的棄用別名，在 future 操作超過給定超時 (timeout) 時引發。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.11 版的變更: </span>這個類別是 <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> 的別名。</p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.BrokenExecutor">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">BrokenExecutor</span></span><a class="headerlink" href="#concurrent.futures.BrokenExecutor" title="連結到這個定義">¶</a></dt>
<dd><p>衍生自 <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>，當執行器因某種原因損壞時會引發此例外類別，並且不能用於提交或執行新任務。</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.7 版被加入.</span></p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.InvalidStateError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">InvalidStateError</span></span><a class="headerlink" href="#concurrent.futures.InvalidStateError" title="連結到這個定義">¶</a></dt>
<dd><p>目前狀態下不允許的 future 操作被執行時而引發。</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.8 版被加入.</span></p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.thread.BrokenThreadPool">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.thread.</span></span><span class="sig-name descname"><span class="pre">BrokenThreadPool</span></span><a class="headerlink" href="#concurrent.futures.thread.BrokenThreadPool" title="連結到這個定義">¶</a></dt>
<dd><p>衍生自 <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenExecutor</span></code></a>，當 <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> 的其中一個 worker 初始化失敗時會引發此例外類別。</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.7 版被加入.</span></p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.interpreter.BrokenInterpreterPool">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.interpreter.</span></span><span class="sig-name descname"><span class="pre">BrokenInterpreterPool</span></span><a class="headerlink" href="#concurrent.futures.interpreter.BrokenInterpreterPool" title="連結到這個定義">¶</a></dt>
<dd><p>衍生自 <a class="reference internal" href="#concurrent.futures.thread.BrokenThreadPool" title="concurrent.futures.thread.BrokenThreadPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenThreadPool</span></code></a>，當 <a class="reference internal" href="#concurrent.futures.InterpreterPoolExecutor" title="concurrent.futures.InterpreterPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">InterpreterPoolExecutor</span></code></a> 的其中一個 worker 初始化失敗時會引發此例外類別。</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.14 版被加入.</span></p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="concurrent.futures.process.BrokenProcessPool">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.process.</span></span><span class="sig-name descname"><span class="pre">BrokenProcessPool</span></span><a class="headerlink" href="#concurrent.futures.process.BrokenProcessPool" title="連結到這個定義">¶</a></dt>
<dd><p>衍生自 <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenExecutor</span></code></a>（以前為 <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>），當 <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> 的其中一個 worker 以不乾淨的方式終止時將引發此例外類別（例如它是從外面被 kill 掉的）。</p>
<div class="versionadded">
<p><span class="versionmodified added">在 3.3 版被加入.</span></p>
</div>
</dd></dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">目錄</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> --- 啟動平行任務</a><ul>
<li><a class="reference internal" href="#executor-objects">Executor 物件</a></li>
<li><a class="reference internal" href="#threadpoolexecutor">ThreadPoolExecutor</a><ul>
<li><a class="reference internal" href="#threadpoolexecutor-example">ThreadPoolExecutor 範例</a></li>
</ul>
</li>
<li><a class="reference internal" href="#interpreterpoolexecutor">InterpreterPoolExecutor</a></li>
<li><a class="reference internal" href="#processpoolexecutor">ProcessPoolExecutor</a><ul>
<li><a class="reference internal" href="#processpoolexecutor-example">ProcessPoolExecutor 範例</a></li>
</ul>
</li>
<li><a class="reference internal" href="#future-objects">Future 物件</a></li>
<li><a class="reference internal" href="#module-functions">模組函式</a></li>
<li><a class="reference internal" href="#exception-classes">例外類別</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>上個主題</h4>
<p class="topless"><a href="concurrent.html"
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent</span></code> 套件</a></p>
</div>
<div>
<h4>下個主題</h4>
<p class="topless"><a href="concurrent.interpreters.html"
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.interpreters</span></code> --- 在同一個行程中使用多個直譯器</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/concurrent.futures.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>此頁面</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">回報錯誤</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">改進此頁面</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/concurrent.futures.rst?plain=1"
rel="nofollow">顯示原始碼
</a>
</li>
<li>
<a href="https://github.com/python/python-docs-zh-TW/blob/3.14/library/concurrent.futures.po?plain=1"
rel="nofollow">顯示翻譯原始碼</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="收合側邊欄">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>導航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="總索引"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="concurrent.interpreters.html" title="concurrent.interpreters --- 在同一個行程中使用多個直譯器"
>下一頁</a> |</li>
<li class="right" >
<a href="concurrent.html" title="concurrent 套件"
>上一頁</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.14.5 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python 標準函式庫 (Standard Library)</a> »</li>
<li class="nav-item nav-item-2"><a href="concurrency.html" >並行執行 (Concurrent Execution)</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> --- 啟動平行任務</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="search" name="q" id="search-box">
<input type="submit" value="前往">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
主題
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>自動</option>
<option value="light">淺色模式</option>
<option value="dark">深色模式</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">版權所有</a> 2001 Python Software Foundation.
<br>
此頁面採用 Python 軟體基金會授權條款第 2 版。
<br>
文件中的範例、應用技巧與其他程式碼額外採用了 Zero Clause BSD 授權條款。
<br>
更多訊息請見<a href="/license.html">歷史與授權條款</a>。<br>
<br>
Python 軟體基金會是一家非營利法人。
<a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
<br>
<br>
最後更新於 5月 14, 2026 (19:12 UTC)。
<a href="/bugs.html">發現 bug</a>？
<br>
以 <a href="https://www.sphinx-doc.org/">Sphinx</a>8.2.3建立。
</div>
</body>
</html>