python-docs-fa/c-api/threads.html at gh-pages · python/python-docs-fa

History

1234 lines (1134 loc) · 114 KB

Raw

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

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html>

<head>

<title>Thread states and the global interpreter lock — مستندات Python3.14.6</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

title="جستجو در مستندات Python3.14.6"

href="../_static/opensearch.xml"/>

<style>

@media only screen {

table.full-width-table {

width: 100%;

}

</style>

</head>

<body>

<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">

</label>

</a>

</svg>

</form>

</nav>

Theme

<option value="light">Light</option>

</select>

</label>

<div>

<h3><a href="../contents.html">فهرست عناوین</a></h3>

<ul>

<li><a class="reference internal" href="#">Thread states and the global interpreter lock</a><ul>

<li><a class="reference internal" href="#detaching-the-thread-state-from-extension-code">Detaching the thread state from extension code</a><ul>

</ul>

</li>

<li><a class="reference internal" href="#non-python-created-threads">Non-Python created threads</a></li>

<li><a class="reference internal" href="#legacy-api">Legacy API</a></li>

<li><a class="reference internal" href="#cautions-about-fork">Cautions about fork()</a></li>

<li><a class="reference internal" href="#high-level-apis">High-level APIs</a></li>

<li><a class="reference internal" href="#gil-state-apis">GIL-state APIs</a></li>

<li><a class="reference internal" href="#low-level-apis">Low-level APIs</a></li>

</ul>

</li>

<li><a class="reference internal" href="#asynchronous-notifications">Asynchronous notifications</a></li>

<li><a class="reference internal" href="#operating-system-thread-apis">Operating system thread APIs</a></li>

</ul>

</div>

<div>

<h4>موضوع قبلی</h4>

<a href="interp-lifecycle.html"

title="فصل قبلی">Interpreter initialization and finalization</a>

</div>

<div>

<h4>موضوع بعدی</h4>

<a href="synchronization.html"

title="فصل بعدی">Synchronization primitives</a>

</div>

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', "c-api/threads.rst");

element.href = url.toString();

});

</script>

<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/c-api/threads.rst?plain=1"

rel="nofollow">نمایش منبع

</a>

</li>

<li>

<a href="https://github.com/python/python-docs-fa/blob/3.14/c-api/threads.po?plain=1"

rel="nofollow">نمایش منبع ترجمه</a>

</li>

</ul>

</div>

</nav>

</div>

<h3>ناوبری</h3>

<ul>

<a href="../genindex.html" title="فهرست کلی"

accesskey="I">فهرست</a></li>

<a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"

>ماژول ها</a> |</li>

<a href="synchronization.html" title="Synchronization primitives"

accesskey="N">بعدی</a> |</li>

<a href="interp-lifecycle.html" title="Interpreter initialization and finalization"

accesskey="P">قبلی</a> |</li>

<li><a href="https://www.python.org/">Python</a> »</li>

</li>

<li>

</li>

<a href="../index.html">3.14.6 Documentation</a> »

</li>

<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API reference manual</a> »</li>

<li class="nav-item nav-item-this"><a href="">Thread states and the global interpreter lock</a></li>

</form>

</div>

</li>

Theme

<option value="light">Light</option>

</select>

</label> |</li>

</ul>

</div>

<h1>Thread states and the global interpreter lock<a class="headerlink" href="#thread-states-and-the-global-interpreter-lock" title="Link to this heading">¶</a></h1>

Unless on a <a class="reference internal" href="../glossary.html#term-free-threaded-build">free-threaded build</a> of <a class="reference internal" href="../glossary.html#term-CPython">CPython</a>,

the Python interpreter is generally not thread-safe. In order to support

multi-threaded Python programs, there's a global lock, called the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock">global

interpreter lock</a> or <a class="reference internal" href="../glossary.html#term-GIL">GIL</a>, that must be held by a thread before

accessing Python objects. Without the lock, even the simplest operations

could cause problems in a multi-threaded program: for example, when

two threads simultaneously increment the reference count of the same object, the

reference count could end up being incremented only once instead of twice.

As such, only a thread that holds the GIL may operate on Python objects or

invoke Python's C API.

In order to emulate concurrency, the interpreter regularly tries to switch

threads between bytecode instructions (see <a class="reference internal" href="../library/sys.html#sys.setswitchinterval" title="sys.setswitchinterval"><code class="xref py py-func docutils literal notranslate">sys.setswitchinterval()</code></a>).

This is why locks are also necessary for thread-safety in pure-Python code.

Additionally, the global interpreter lock is released around blocking I/O

operations, such as reading or writing to a file. From the C API, this is done

by <a class="reference internal" href="#detaching-thread-state">detaching the thread state</a>.

The Python interpreter keeps some thread-local information inside

a data structure called <a class="reference internal" href="#c.PyThreadState" title="PyThreadState"><code class="xref c c-type docutils literal notranslate">PyThreadState</code></a>, known as a <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a>.

Each thread has a thread-local pointer to a <code class="xref c c-type docutils literal notranslate">PyThreadState</code>; a thread state

referenced by this pointer is considered to be <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a>.

A thread can only have one <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> at a time. An attached

thread state is typically analogous with holding the GIL, except on

free-threaded builds. On builds with the GIL enabled, attaching a thread state

will block until the GIL can be acquired. However, even on builds with the GIL

disabled, it is still required to have an attached thread state, as the interpreter

needs to keep track of which threads may access Python objects.

توجه

Even on the free-threaded build, attaching a thread state may block, as the

GIL can be re-enabled or threads might be temporarily suspended (such as during

a garbage collection).

</div>

Generally, there will always be an attached thread state when using Python's

C API, including during embedding and when implementing methods, so it's uncommon

to need to set up a thread state on your own. Only in some specific cases, such

as in a <a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code></a> block or in a fresh thread, will the

thread not have an attached thread state.

If uncertain, check if <a class="reference internal" href="#c.PyThreadState_GetUnchecked" title="PyThreadState_GetUnchecked"><code class="xref c c-func docutils literal notranslate">PyThreadState_GetUnchecked()</code></a> returns <code class="docutils literal notranslate">NULL</code>.

If it turns out that you do need to create a thread state, call <a class="reference internal" href="#c.PyThreadState_New" title="PyThreadState_New"><code class="xref c c-func docutils literal notranslate">PyThreadState_New()</code></a>

followed by <a class="reference internal" href="#c.PyThreadState_Swap" title="PyThreadState_Swap"><code class="xref c c-func docutils literal notranslate">PyThreadState_Swap()</code></a>, or use the dangerous

<h2>Detaching the thread state from extension code<a class="headerlink" href="#detaching-the-thread-state-from-extension-code" title="Link to this heading">¶</a></h2>

Most extension code manipulating the <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> has the following simple

structure:

<div class="highlight-c notranslate"><div class="highlight"><pre>Save the thread state in a local variable.

... Do some blocking I/O operation ...

Restore the thread state from the local variable.

</pre></div>

</div>

This is so common that a pair of macros exists to simplify it:

<div class="highlight-c notranslate"><div class="highlight"><pre>Py_BEGIN_ALLOW_THREADS

Py_END_ALLOW_THREADS

</pre></div>

</div>

The <a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code></a> macro opens a new block and declares a

hidden local variable; the <a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_END_ALLOW_THREADS</code></a> macro closes the

block.

The block above expands to the following code:

<div class="highlight-c notranslate"><div class="highlight"><pre>PyThreadState *_save;

_save = PyEval_SaveThread();

PyEval_RestoreThread(_save);

</pre></div>

</div>

Here is how these functions work:

The attached thread state implies that the GIL is held for the interpreter.

To detach it, <a class="reference internal" href="#c.PyEval_SaveThread" title="PyEval_SaveThread"><code class="xref c c-func docutils literal notranslate">PyEval_SaveThread()</code></a> is called and the result is stored

in a local variable.

By detaching the thread state, the GIL is released, which allows other threads

to attach to the interpreter and execute while the current thread performs

blocking I/O. When the I/O operation is complete, the old thread state is

reattached by calling <a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate">PyEval_RestoreThread()</code></a>, which will wait until

the GIL can be acquired.

توجه

Performing blocking I/O is the most common use case for detaching

the thread state, but it is also useful to call it over long-running

native code that doesn't need access to Python objects or Python's C API.

For example, the standard <a class="reference internal" href="../library/zlib.html#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code class="xref py py-mod docutils literal notranslate">zlib</code></a> and <a class="reference internal" href="../library/hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal notranslate">hashlib</code></a> modules detach the

<a class="reference internal" href="../glossary.html#term-attached-thread-state">thread state</a> when compressing or hashing

data.

</div>

On a <a class="reference internal" href="../glossary.html#term-free-threaded-build">free-threaded build</a>, the <a class="reference internal" href="../glossary.html#term-GIL">GIL</a> is usually out of the question,

but detaching the thread state is still required, because the interpreter

periodically needs to block all threads to get a consistent view of Python objects

without the risk of race conditions.

For example, CPython currently suspends all threads for a short period of time

while running the garbage collector.

هشدار

Detaching the thread state can lead to unexpected behavior during interpreter

finalization. See <a class="reference internal" href="interp-lifecycle.html#cautions-regarding-runtime-finalization">Cautions regarding runtime finalization</a> for more

details.

</div>

The following macros are normally used without a trailing semicolon; look for

example usage in the Python source distribution.

توجه

These macros are still necessary on the <a class="reference internal" href="../glossary.html#term-free-threaded-build">free-threaded build</a> to prevent

deadlocks.

</div>

Py_BEGIN_ALLOW_THREADS<a class="headerlink" href="#c.Py_BEGIN_ALLOW_THREADS" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This macro expands to <code class="docutils literal notranslate">{ PyThreadState *_save; _save = PyEval_SaveThread();</code>.

Note that it contains an opening brace; it must be matched with a following

<a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_END_ALLOW_THREADS</code></a> macro. See above for further discussion of this

macro.

</dd></dl>

Py_END_ALLOW_THREADS<a class="headerlink" href="#c.Py_END_ALLOW_THREADS" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This macro expands to <code class="docutils literal notranslate">PyEval_RestoreThread(_save); }</code>. Note that it contains

a closing brace; it must be matched with an earlier

this macro.

</dd></dl>

Py_BLOCK_THREADS<a class="headerlink" href="#c.Py_BLOCK_THREADS" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This macro expands to <code class="docutils literal notranslate">PyEval_RestoreThread(_save);</code>: it is equivalent to

</dd></dl>

Py_UNBLOCK_THREADS<a class="headerlink" href="#c.Py_UNBLOCK_THREADS" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This macro expands to <code class="docutils literal notranslate">_save = PyEval_SaveThread();</code>: it is equivalent to

declaration.

</dd></dl>

</section>

<h2>Non-Python created threads<a class="headerlink" href="#non-python-created-threads" title="Link to this heading">¶</a></h2>

When threads are created using the dedicated Python APIs (such as the

<a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate">threading</code></a> module), a thread state is automatically associated with them,

However, when a thread is created from native code (for example, by a

third-party library with its own thread management), it doesn't hold an

attached thread state.

If you need to call Python code from these threads (often this will be part

of a callback API provided by the aforementioned third-party library),

you must first register these threads with the interpreter by

creating a new thread state and attaching it.

The most robust way to do this is through <a class="reference internal" href="#c.PyThreadState_New" title="PyThreadState_New"><code class="xref c c-func docutils literal notranslate">PyThreadState_New()</code></a> followed

by <a class="reference internal" href="#c.PyThreadState_Swap" title="PyThreadState_Swap"><code class="xref c c-func docutils literal notranslate">PyThreadState_Swap()</code></a>.

توجه

<code class="docutils literal notranslate">PyThreadState_New</code> requires an argument pointing to the desired

interpreter; such a pointer can be acquired via a call to

<a class="reference internal" href="subinterpreters.html#c.PyInterpreterState_Get" title="PyInterpreterState_Get"><code class="xref c c-func docutils literal notranslate">PyInterpreterState_Get()</code></a> from the code where the thread was

created.

</div>

For example:

<div class="highlight-c notranslate"><div class="highlight"><pre>/* The return value of PyInterpreterState_Get() from the

function that created this thread. */

PyInterpreterState *interp = thread_data->interp;

/* Create a new thread state for the interpreter. It does not start out

attached. */

PyThreadState *tstate = PyThreadState_New(interp);

/* Attach the thread state, which will acquire the GIL. */

PyThreadState_Swap(tstate);

/* Perform Python actions here. */

result = CallSomeFunction();

/* evaluate result or handle exception */

/* Destroy the thread state. No Python API allowed beyond this point. */

PyThreadState_Clear(tstate);

PyThreadState_DeleteCurrent();

</pre></div>

</div>

هشدار

If the interpreter finalized before <code class="docutils literal notranslate">PyThreadState_Swap</code> was called, then

<code class="docutils literal notranslate">interp</code> will be a dangling pointer!

</div>

</section>

<h2>Legacy API<a class="headerlink" href="#legacy-api" title="Link to this heading">¶</a></h2>

Another common pattern to call Python code from a non-Python thread is to use

<a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> followed by a call to <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate">PyGILState_Release()</code></a>.

These functions do not work well when multiple interpreters exist in the Python

process. If no Python interpreter has ever been used in the current thread (which

is common for threads created outside Python), <code class="docutils literal notranslate">PyGILState_Ensure</code> will create

and attach a thread state for the "main" interpreter (the first interpreter in

the Python process).

Additionally, these functions have thread-safety issues during interpreter

finalization. Using <code class="docutils literal notranslate">PyGILState_Ensure</code> during finalization will likely

crash the process.

Usage of these functions look like such:

<div class="highlight-c notranslate"><div class="highlight"><pre>PyGILState_STATE gstate;

gstate = PyGILState_Ensure();

/* Perform Python actions here. */

result = CallSomeFunction();

/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */

PyGILState_Release(gstate);

</pre></div>

</div>

</section>

<h2>Cautions about fork()<a class="headerlink" href="#cautions-about-fork" title="Link to this heading">¶</a></h2>

Another important thing to note about threads is their behaviour in the face

of the C <code class="xref c c-func docutils literal notranslate">fork()</code> call. On most systems with <code class="xref c c-func docutils literal notranslate">fork()</code>, after a

process forks only the thread that issued the fork will exist. This has a

concrete impact both on how locks must be handled and on all stored state

in CPython's runtime.

The fact that only the "current" thread remains

means any locks held by other threads will never be released. Python solves

this for <a class="reference internal" href="../library/os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate">os.fork()</code></a> by acquiring the locks it uses internally before

the fork, and releasing them afterwards. In addition, it resets any

<a class="reference internal" href="../library/threading.html#lock-objects">Lock objects</a> in the child. When extending or embedding Python, there

is no way to inform Python of additional (non-Python) locks that need to be

acquired before or reset after a fork. OS facilities such as

<code class="xref c c-func docutils literal notranslate">pthread_atfork()</code> would need to be used to accomplish the same thing.

Additionally, when extending or embedding Python, calling <code class="xref c c-func docutils literal notranslate">fork()</code>

directly rather than through <code class="xref py py-func docutils literal notranslate">os.fork()</code> (and returning to or calling

into Python) may result in a deadlock by one of Python's internal locks

being held by a thread that is defunct after the fork.

<a class="reference internal" href="sys.html#c.PyOS_AfterFork_Child" title="PyOS_AfterFork_Child"><code class="xref c c-func docutils literal notranslate">PyOS_AfterFork_Child()</code></a> tries to reset the necessary locks, but is not

always able to.

The fact that all other threads go away also means that CPython's

runtime state there must be cleaned up properly, which <a class="reference internal" href="../library/os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate">os.fork()</code></a>

does. This means finalizing all other <a class="reference internal" href="#c.PyThreadState" title="PyThreadState"><code class="xref c c-type docutils literal notranslate">PyThreadState</code></a> objects

belonging to the current interpreter and all other

<a class="reference internal" href="subinterpreters.html#c.PyInterpreterState" title="PyInterpreterState"><code class="xref c c-type docutils literal notranslate">PyInterpreterState</code></a> objects. Due to this and the special

nature of the <a class="reference internal" href="subinterpreters.html#sub-interpreter-support">"main" interpreter</a>,

<code class="xref c c-func docutils literal notranslate">fork()</code> should only be called in that interpreter's "main"

thread, where the CPython global runtime was originally initialized.

The only exception is if <code class="xref c c-func docutils literal notranslate">exec()</code> will be called immediately

after.

</section>

<h2>High-level APIs<a class="headerlink" href="#high-level-apis" title="Link to this heading">¶</a></h2>

These are the most commonly used types and functions when writing multi-threaded

C extensions.

type PyThreadState<a class="headerlink" href="#c.PyThreadState" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">API محدود</a> (به‌عنوان یک ساختار مبهم).This data structure represents the state of a single thread. The only public

data member is:

<dd>This thread's interpreter state.

</dd></dl>

void PyEval_InitThreads()<a class="headerlink" href="#c.PyEval_InitThreads" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Deprecated function which does nothing.

In Python 3.6 and older, this function created the GIL if it didn't exist.

تغییر داده شده در نسخه 3.9: The function now does nothing.

</div>

تغییر داده شده در نسخه 3.7: This function is now called by <a class="reference internal" href="interp-lifecycle.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate">Py_Initialize()</code></a>, so you don't

have to call it yourself anymore.

</div>

تغییر داده شده در نسخه 3.2: This function cannot be called before <a class="reference internal" href="interp-lifecycle.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate">Py_Initialize()</code></a> anymore.

</div>

منسوخ شده از نسخه 3.9.

</div>

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Detach the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> and return it.

The thread will have no <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> upon returning.

</dd></dl>

void PyEval_RestoreThread(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyEval_RestoreThread" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Set the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> to tstate.

The passed <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> should not be attached,

otherwise deadlock ensues. tstate will be attached upon returning.

توجه

Calling this function from a thread when the runtime is finalizing will

hang the thread until the program exits, even if the thread was not

created by Python. Refer to

<a class="reference internal" href="interp-lifecycle.html#cautions-regarding-runtime-finalization">Cautions regarding runtime finalization</a> for more details.

</div>

تغییر داده شده در نسخه 3.14: Hangs the current thread, rather than terminating it, if called while the

interpreter is finalizing.

</div>

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Return the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>. If the thread has no attached

thread state, (such as when inside of <a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code></a>

block), then this issues a fatal error (so that the caller needn't check

for <code class="docutils literal notranslate">NULL</code>).

See also <a class="reference internal" href="#c.PyThreadState_GetUnchecked" title="PyThreadState_GetUnchecked"><code class="xref c c-func docutils literal notranslate">PyThreadState_GetUnchecked()</code></a>.

</dd></dl>

<dd>Similar to <a class="reference internal" href="#c.PyThreadState_Get" title="PyThreadState_Get"><code class="xref c c-func docutils literal notranslate">PyThreadState_Get()</code></a>, but don't kill the process with a

fatal error if it is NULL. The caller is responsible to check if the result

is NULL.

Added in version 3.13: In Python 3.5 to 3.12, the function was private and known as

<code class="docutils literal notranslate">_PyThreadState_UncheckedGet()</code>.

</div>

</dd></dl>

<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *PyThreadState_Swap(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_Swap" title="Link to this definition">¶</a> </dt>

<a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> that was attached prior to calling.

This function is safe to call without an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>; it

will simply return <code class="docutils literal notranslate">NULL</code> indicating that there was no prior thread state.

همچنین ملاحظه نمائید

<a class="reference internal" href="#c.PyEval_ReleaseThread" title="PyEval_ReleaseThread"><code class="xref c c-func docutils literal notranslate">PyEval_ReleaseThread()</code></a>

</div>

توجه

Similar to <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a>, this function will hang the

thread if the runtime is finalizing.

</div>

</dd></dl>

</section>

<h2>GIL-state APIs<a class="headerlink" href="#gil-state-apis" title="Link to this heading">¶</a></h2>

The following functions use thread-local storage, and are not compatible

with sub-interpreters:

type PyGILState_STATE<a class="headerlink" href="#c.PyGILState_STATE" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.The type of the value returned by <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> and passed to

<a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate">PyGILState_Release()</code></a>.

enumerator PyGILState_LOCKED<a class="headerlink" href="#c.PyGILState_STATE.PyGILState_LOCKED" title="Link to this definition">¶</a> </dt>

<dd>The GIL was already held when <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> was called.

</dd></dl>

enumerator PyGILState_UNLOCKED<a class="headerlink" href="#c.PyGILState_STATE.PyGILState_UNLOCKED" title="Link to this definition">¶</a> </dt>

<dd>The GIL was not held when <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> was called.

</dd></dl>

<a class="reference internal" href="#c.PyGILState_STATE" title="PyGILState_STATE">PyGILState_STATE</a> PyGILState_Ensure()<a class="headerlink" href="#c.PyGILState_Ensure" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Ensure that the current thread is ready to call the Python C API regardless

of the current state of Python, or of the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>. This may

be called as many times as desired by a thread as long as each call is

matched with a call to <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate">PyGILState_Release()</code></a>. In general, other

thread-related APIs may be used between <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> and

<code class="xref c c-func docutils literal notranslate">PyGILState_Release()</code> calls as long as the thread state is restored to

its previous state before the Release(). For example, normal usage of the

<a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code></a> and <a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate">Py_END_ALLOW_THREADS</code></a> macros is

acceptable.

The return value is an opaque "handle" to the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> when

though recursive calls are allowed, these handles cannot be shared - each

unique call to <code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code> must save the handle for its call

to <code class="xref c c-func docutils literal notranslate">PyGILState_Release()</code>.

When the function returns, there will be an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>

and the thread will be able to call arbitrary Python code. Failure is a fatal error.

هشدار

Calling this function when the runtime is finalizing is unsafe. Doing

so will either hang the thread until the program ends, or fully crash

the interpreter in rare cases. Refer to

<a class="reference internal" href="interp-lifecycle.html#cautions-regarding-runtime-finalization">Cautions regarding runtime finalization</a> for more details.

</div>

تغییر داده شده در نسخه 3.14: Hangs the current thread, rather than terminating it, if called while the

interpreter is finalizing.

</div>

</dd></dl>

void PyGILState_Release(<a class="reference internal" href="#c.PyGILState_STATE" title="PyGILState_STATE">PyGILState_STATE</a>)<a class="headerlink" href="#c.PyGILState_Release" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Release any resources previously acquired. After this call, Python's state will

be the same as it was prior to the corresponding <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> call

(but generally this state will be unknown to the caller, hence the use of the

GILState API).

Every call to <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> must be matched by a call to

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Get the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> for this thread. May return <code class="docutils literal notranslate">NULL</code> if no

GILState API has been used on the current thread. Note that the main thread

always has such a thread-state, even if no auto-thread-state call has been

made on the main thread. This is mainly a helper/diagnostic function.

توجه

This function may return non-<code class="docutils literal notranslate">NULL</code> even when the <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a>

is detached.

Prefer <a class="reference internal" href="#c.PyThreadState_Get" title="PyThreadState_Get"><code class="xref c c-func docutils literal notranslate">PyThreadState_Get()</code></a> or <a class="reference internal" href="#c.PyThreadState_GetUnchecked" title="PyThreadState_GetUnchecked"><code class="xref c c-func docutils literal notranslate">PyThreadState_GetUnchecked()</code></a>

for most cases.

</div>

همچنین ملاحظه نمائید

<a class="reference internal" href="#c.PyThreadState_Get" title="PyThreadState_Get"><code class="xref c c-func docutils literal notranslate">PyThreadState_Get()</code></a>

</div>

</dd></dl>

int PyGILState_Check()<a class="headerlink" href="#c.PyGILState_Check" title="Link to this definition">¶</a> </dt>

<dd>Return <code class="docutils literal notranslate">1</code> if the current thread is holding the <a class="reference internal" href="../glossary.html#term-GIL">GIL</a> and <code class="docutils literal notranslate">0</code> otherwise.

This function can be called from any thread at any time.

Only if it has had its <a class="reference internal" href="../glossary.html#term-attached-thread-state">thread state</a> initialized

via <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a> will it return <code class="docutils literal notranslate">1</code>.

This is mainly a helper/diagnostic function. It can be useful

for example in callback contexts or memory allocation functions when

knowing that the GIL is locked can allow the caller to perform sensitive

actions or otherwise behave differently.

توجه

If the current Python process has ever created a subinterpreter, this

function will always return <code class="docutils literal notranslate">1</code>. Prefer <a class="reference internal" href="#c.PyThreadState_GetUnchecked" title="PyThreadState_GetUnchecked"><code class="xref c c-func docutils literal notranslate">PyThreadState_GetUnchecked()</code></a>

for most cases.

</div>

Added in version 3.4.

</div>

</dd></dl>

</section>

<h2>Low-level APIs<a class="headerlink" href="#low-level-apis" title="Link to this heading">¶</a></h2>

<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *PyThreadState_New(<a class="reference internal" href="subinterpreters.html#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a> *interp)<a class="headerlink" href="#c.PyThreadState_New" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Create a new thread state object belonging to the given interpreter object.

An <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> is not needed.

</dd></dl>

void PyThreadState_Clear(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_Clear" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Reset all information in a <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> object. tstate

must be <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a>

تغییر داده شده در نسخه 3.9: This function now calls the <code class="xref c c-member docutils literal notranslate">PyThreadState.on_delete</code> callback.

Previously, that happened in <a class="reference internal" href="#c.PyThreadState_Delete" title="PyThreadState_Delete"><code class="xref c c-func docutils literal notranslate">PyThreadState_Delete()</code></a>.

</div>

تغییر داده شده در نسخه 3.13: The <code class="xref c c-member docutils literal notranslate">PyThreadState.on_delete</code> callback was removed.

</div>

</dd></dl>

void PyThreadState_Delete(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_Delete" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Destroy a <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> object. tstate should not

be <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a> to any thread.

tstate must have been reset with a previous call to

<a class="reference internal" href="#c.PyThreadState_Clear" title="PyThreadState_Clear"><code class="xref c c-func docutils literal notranslate">PyThreadState_Clear()</code></a>.

</dd></dl>

void PyThreadState_DeleteCurrent(void)<a class="headerlink" href="#c.PyThreadState_DeleteCurrent" title="Link to this definition">¶</a> </dt>

<dd>Detach the <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> (which must have been reset

with a previous call to <a class="reference internal" href="#c.PyThreadState_Clear" title="PyThreadState_Clear"><code class="xref c c-func docutils literal notranslate">PyThreadState_Clear()</code></a>) and then destroy it.

No <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> will be <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a> upon

returning.

</dd></dl>

<a class="reference internal" href="frame.html#c.PyFrameObject" title="PyFrameObject">PyFrameObject</a> *PyThreadState_GetFrame(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_GetFrame" title="Link to this definition">¶</a> </dt>

Return a <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a>. Return <code class="docutils literal notranslate">NULL</code> if no frame is currently

executing.

See also <a class="reference internal" href="reflection.html#c.PyEval_GetFrame" title="PyEval_GetFrame"><code class="xref c c-func docutils literal notranslate">PyEval_GetFrame()</code></a>.

tstate must not be <code class="docutils literal notranslate">NULL</code>, and must be <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a>.

Added in version 3.9.

</div>

</dd></dl>

uint64_t PyThreadState_GetID(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_GetID" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.10.Get the unique <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a> identifier of the Python thread state tstate.

Added in version 3.9.

</div>

</dd></dl>

<a class="reference internal" href="subinterpreters.html#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a> *PyThreadState_GetInterpreter(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_GetInterpreter" title="Link to this definition">¶</a> </dt>

Added in version 3.9.

</div>

</dd></dl>

void PyThreadState_EnterTracing(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_EnterTracing" title="Link to this definition">¶</a> </dt>

<dd>Suspend tracing and profiling in the Python thread state tstate.

Resume them using the <a class="reference internal" href="#c.PyThreadState_LeaveTracing" title="PyThreadState_LeaveTracing"><code class="xref c c-func docutils literal notranslate">PyThreadState_LeaveTracing()</code></a> function.

Added in version 3.11.

</div>

</dd></dl>

void PyThreadState_LeaveTracing(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyThreadState_LeaveTracing" title="Link to this definition">¶</a> </dt>

<dd>Resume tracing and profiling in the Python thread state tstate suspended

by the <a class="reference internal" href="#c.PyThreadState_EnterTracing" title="PyThreadState_EnterTracing"><code class="xref c c-func docutils literal notranslate">PyThreadState_EnterTracing()</code></a> function.

See also <a class="reference internal" href="profiling.html#c.PyEval_SetTrace" title="PyEval_SetTrace"><code class="xref c c-func docutils literal notranslate">PyEval_SetTrace()</code></a> and <a class="reference internal" href="profiling.html#c.PyEval_SetProfile" title="PyEval_SetProfile"><code class="xref c c-func docutils literal notranslate">PyEval_SetProfile()</code></a>

functions.

Added in version 3.11.

</div>

</dd></dl>

int PyUnstable_ThreadState_SetStackProtection(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate, void *stack_start_addr, size_t stack_size)<a class="headerlink" href="#c.PyUnstable_ThreadState_SetStackProtection" title="Link to this definition">¶</a> </dt>

این است <a class="reference internal" href="stable.html#unstable-c-api">API ناپایدار</a>این ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.</div>

Set the stack protection start address and stack protection size

of a Python thread state.

On success, return <code class="docutils literal notranslate">0</code>.

On failure, set an exception and return <code class="docutils literal notranslate">-1</code>.

CPython implements <a class="reference internal" href="exceptions.html#recursion">recursion control</a> for C code by raising

<a class="reference internal" href="../library/exceptions.html#RecursionError" title="RecursionError"><code class="xref py py-exc docutils literal notranslate">RecursionError</code></a> when it notices that the machine execution stack is close

to overflow. See for example the <a class="reference internal" href="exceptions.html#c.Py_EnterRecursiveCall" title="Py_EnterRecursiveCall"><code class="xref c c-func docutils literal notranslate">Py_EnterRecursiveCall()</code></a> function.

For this, it needs to know the location of the current thread's stack, which it

normally gets from the operating system.

When the stack is changed, for example using context switching techniques like the

Boost library's <code class="docutils literal notranslate">boost::context</code>, you must call

<a class="reference internal" href="#c.PyUnstable_ThreadState_SetStackProtection" title="PyUnstable_ThreadState_SetStackProtection"><code class="xref c c-func docutils literal notranslate">PyUnstable_ThreadState_SetStackProtection()</code></a> to inform CPython of the change.

Call <a class="reference internal" href="#c.PyUnstable_ThreadState_SetStackProtection" title="PyUnstable_ThreadState_SetStackProtection"><code class="xref c c-func docutils literal notranslate">PyUnstable_ThreadState_SetStackProtection()</code></a> either before

or after changing the stack.

Do not call any other Python C API between the call and the stack

change.

See <a class="reference internal" href="#c.PyUnstable_ThreadState_ResetStackProtection" title="PyUnstable_ThreadState_ResetStackProtection"><code class="xref c c-func docutils literal notranslate">PyUnstable_ThreadState_ResetStackProtection()</code></a> for undoing this operation.

Added in version 3.15.

</div>

</dd></dl>

void PyUnstable_ThreadState_ResetStackProtection(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyUnstable_ThreadState_ResetStackProtection" title="Link to this definition">¶</a> </dt>

Reset the stack protection start address and stack protection size

of a Python thread state to the operating system defaults.

See <a class="reference internal" href="#c.PyUnstable_ThreadState_SetStackProtection" title="PyUnstable_ThreadState_SetStackProtection"><code class="xref c c-func docutils literal notranslate">PyUnstable_ThreadState_SetStackProtection()</code></a> for an explanation.

Added in version 3.15.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyThreadState_GetDict()<a class="headerlink" href="#c.PyThreadState_GetDict" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: مرجع قرضی. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Return a dictionary in which extensions can store thread-specific state

information. Each extension should use a unique key to use to store state in

the dictionary. It is okay to call this function when no <a class="reference internal" href="../glossary.html#term-thread-state">thread state</a>

is <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached</a>. If this function returns

<code class="docutils literal notranslate">NULL</code>, no exception has been raised and the caller should assume no

thread state is attached.

</dd></dl>

void PyEval_AcquireThread(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyEval_AcquireThread" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.<a class="reference internal" href="../glossary.html#term-attached-thread-state">Attach</a> tstate to the current thread,

which must not be <code class="docutils literal notranslate">NULL</code> or already attached.

The calling thread must not already have an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

توجه

Calling this function from a thread when the runtime is finalizing will

hang the thread until the program exits, even if the thread was not

created by Python. Refer to

<a class="reference internal" href="interp-lifecycle.html#cautions-regarding-runtime-finalization">Cautions regarding runtime finalization</a> for more details.

</div>

تغییر داده شده در نسخه 3.8: Updated to be consistent with <a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate">PyEval_RestoreThread()</code></a>,

<a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-func docutils literal notranslate">Py_END_ALLOW_THREADS()</code></a>, and <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate">PyGILState_Ensure()</code></a>,

and terminate the current thread if called while the interpreter is finalizing.

</div>

تغییر داده شده در نسخه 3.14: Hangs the current thread, rather than terminating it, if called while the

interpreter is finalizing.

</div>

<a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate">PyEval_RestoreThread()</code></a> is a higher-level function which is always

available (even when threads have not been initialized).

</dd></dl>

void PyEval_ReleaseThread(<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> *tstate)<a class="headerlink" href="#c.PyEval_ReleaseThread" title="Link to this definition">¶</a> </dt>

The tstate argument, which must not be <code class="docutils literal notranslate">NULL</code>, is only used to check

that it represents the attached thread state --- if it isn't, a fatal error is

reported.

<a class="reference internal" href="#c.PyEval_SaveThread" title="PyEval_SaveThread"><code class="xref c c-func docutils literal notranslate">PyEval_SaveThread()</code></a> is a higher-level function which is always

available (even when threads have not been initialized).

</dd></dl>

</section>

<h1>Asynchronous notifications<a class="headerlink" href="#asynchronous-notifications" title="Link to this heading">¶</a></h1>

A mechanism is provided to make asynchronous notifications to the main

interpreter thread. These notifications take the form of a function

pointer and a void pointer argument.

int Py_AddPendingCall(int (*func)(void*), void *arg)<a class="headerlink" href="#c.Py_AddPendingCall" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Schedule a function to be called from the main interpreter thread. On

success, <code class="docutils literal notranslate">0</code> is returned and func is queued for being called in the

main thread. On failure, <code class="docutils literal notranslate">-1</code> is returned without setting any exception.

When successfully queued, func will be eventually called from the

main interpreter thread with the argument arg. It will be called

asynchronously with respect to normally running Python code, but with

both these conditions met:

<li>on a <a class="reference internal" href="../glossary.html#term-bytecode">bytecode</a> boundary;</li>

<li>with the main thread holding an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>

(func can therefore use the full C API).</li>

</ul>

func must return <code class="docutils literal notranslate">0</code> on success, or <code class="docutils literal notranslate">-1</code> on failure with an exception

set. func won't be interrupted to perform another asynchronous

notification recursively, but it can still be interrupted to switch

threads if the <a class="reference internal" href="../glossary.html#term-attached-thread-state">thread state</a> is detached.

This function doesn't need an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>. However, to call this

function in a subinterpreter, the caller must have an attached thread state.

Otherwise, the function func can be scheduled to be called from the wrong interpreter.

هشدار

This is a low-level function, only useful for very special cases.

There is no guarantee that func will be called as quick as

possible. If the main thread is busy executing a system call,

func won't be called before the system call returns. This

function is generally not suitable for calling Python code from

arbitrary C threads. Instead, use the <a class="reference internal" href="#gilstate">PyGILState API</a>.

</div>

Added in version 3.1.

</div>

تغییر داده شده در نسخه 3.9: If this function is called in a subinterpreter, the function func is

now scheduled to be called from the subinterpreter, rather than being

called from the main interpreter. Each subinterpreter now has its own

list of scheduled calls.

</div>

تغییر داده شده در نسخه 3.12: This function now always schedules func to be run in the main

interpreter.

</div>

</dd></dl>

int Py_MakePendingCalls(void)<a class="headerlink" href="#c.Py_MakePendingCalls" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Execute all pending calls. This is usually executed automatically by the

interpreter.

This function returns <code class="docutils literal notranslate">0</code> on success, and returns <code class="docutils literal notranslate">-1</code> with an exception

set on failure.

If this is not called in the main thread of the main

interpreter, this function does nothing and returns <code class="docutils literal notranslate">0</code>.

The caller must hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

Added in version 3.1.

</div>

تغییر داده شده در نسخه 3.12: This function only runs pending calls in the main interpreter.

</div>

</dd></dl>

int PyThreadState_SetAsyncExc(unsigned long id, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyThreadState_SetAsyncExc" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Asynchronously raise an exception in a thread. The id argument is the thread

id of the target thread; exc is the exception object to be raised. This

function does not steal any references to exc. To prevent naive misuse, you

must write your own C extension to call this. Must be called with an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

Returns the number of thread states modified; this is normally one, but will be

zero if the thread id isn't found. If exc is <code class="docutils literal notranslate">NULL</code>, the pending

exception (if any) for the thread is cleared. This raises no exceptions.

تغییر داده شده در نسخه 3.7: The type of the id parameter changed from long to

unsigned long.

</div>

</dd></dl>

</section>

<h1>Operating system thread APIs<a class="headerlink" href="#operating-system-thread-apis" title="Link to this heading">¶</a></h1>

PYTHREAD_INVALID_THREAD_ID<a class="headerlink" href="#c.PYTHREAD_INVALID_THREAD_ID" title="Link to this definition">¶</a> </dt>

<dd>Sentinel value for an invalid thread ID.

This is currently equivalent to <code class="docutils literal notranslate">(unsigned long)-1</code>.

</dd></dl>

unsigned long PyThread_start_new_thread(void (*func)(void*), void *arg)<a class="headerlink" href="#c.PyThread_start_new_thread" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Start function func in a new thread with argument arg.

The resulting thread is not intended to be joined.

func must not be <code class="docutils literal notranslate">NULL</code>, but arg may be <code class="docutils literal notranslate">NULL</code>.

On success, this function returns the identifier of the new thread; on failure,

this returns <a class="reference internal" href="#c.PYTHREAD_INVALID_THREAD_ID" title="PYTHREAD_INVALID_THREAD_ID"><code class="xref c c-macro docutils literal notranslate">PYTHREAD_INVALID_THREAD_ID</code></a>.

The caller does not need to hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Return the identifier of the current thread, which will never be zero.

This function cannot fail, and the caller does not need to hold an

<a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

همچنین ملاحظه نمائید

<a class="reference internal" href="../library/threading.html#threading.get_ident" title="threading.get_ident"><code class="xref py py-func docutils literal notranslate">threading.get_ident()</code></a>

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyThread_GetInfo(void)<a class="headerlink" href="#c.PyThread_GetInfo" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.3.Get general information about the current thread in the form of a

<a class="reference internal" href="tuple.html#struct-sequence-objects">struct sequence</a> object. This information is

accessible as <a class="reference internal" href="../library/sys.html#sys.thread_info" title="sys.thread_info"><code class="xref py py-attr docutils literal notranslate">sys.thread_info</code></a> in Python.

On success, this returns a new <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> to the thread

information; on failure, this returns <code class="docutils literal notranslate">NULL</code> with an exception set.

View remainder of file in raw view

Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

threads.html

Latest commit

History

threads.html

File metadata and controls