GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-145912: Add a free-threading section on testing with ThreadSanitizer by johng · Pull Request #161165 · python/cpython

Conversation

@johng

@johng johng commented Nov 2, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

Part of the free-threading docs tracking issue (gh-145912).

The only documentation of ThreadSanitizer was the one-line --with-thread-sanitizer entry in using/configure.rst. This adds a "Testing with ThreadSanitizer" section to the free-threading extensions HOWTO covering:

  • building a free-threaded interpreter with TSan (--disable-gil --with-thread-sanitizer)
  • how extensions built with that interpreter are instrumented, and that uninstrumented code is not checked
  • what a report looks like, and TSAN_OPTIONS / the suppressions file in Tools/tsan/
  • running CPython's TSan tests (--tsan, --tsan-parallel)
  • that TSan reports C-level data races, not logic races in Python code

using/configure.rst now links to it from --with-thread-sanitizer.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@johng
Docs: add a free-threading section on testing with ThreadSanitizer
a81eeec 
There was no documentation on using ThreadSanitizer with the free-threaded
build beyond the configure option. Describe how to build, how extensions are
instrumented, how to read a report, and how to run CPython's TSan tests, and
note that TSan does not detect logic races in Python code.
@johng
johng requested review from AA-Turner, corona10 and erlend-aasland as code owners November 2, 2026 09:49
@bedevere-app bedevere-app Bot added the awaiting review label Nov 2, 2026
@johng
johng requested review from emmatyping and itamaro as code owners November 2, 2026 09:49
@bedevere-app bedevere-app Bot mentioned this pull request Nov 2, 2026
Tracking issue for free-threading docs #145912
Open
18 of 49 tasks
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Nov 2, 2026
@github-project-automation github-project-automation Bot added this to Docs PRs Nov 2, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Nov 2, 2026
@johng

johng commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

I can't say I'm an expert on using TSAN only using what has been required to find some FT bugs in the past (so maybe some better people to have raised/reviewed this), from what I can see this is correct and enough to get started though
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@johng
Docs: fix highlighting of the ThreadSanitizer examples
6cdf257 
The HOWTO sets the default highlight language to C, so the TSan report was
lexed as C and raised a highlighting warning. Mark it, and the shell
commands, with explicit languages.
@read-the-docs-community

read-the-docs-community Bot commented Nov 2, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35590905 | 📁 Comparing 9ea1e7d against main (86be79a)

  🔍 Preview build  

2 files changed
± howto/free-threading-extensions.html
± whatsnew/changelog.html
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
corona10
corona10 reviewed Nov 2, 2026
View reviewed changes
Comment thread Doc/using/configure.rst Outdated
Enable ThreadSanitizer data race detector, ``tsan``
(default is no).
(default is no). It is most useful together with :option:`--disable-gil`.
See :ref:`freethreading-tsan`.

@corona10 corona10 Nov 2, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is acutally needed?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@johng johng Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had made this in relation to FT but Doc/howto/free-threading-extensions.rst change should be enough of a reference?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@johng
Docs: drop the configure.rst cross-reference to the TSan section
9ea1e7d
@johng
johng requested a review from corona10 November 2, 2026 19:07
StanFromIreland
StanFromIreland reviewed Nov 2, 2026
View reviewed changes
Comment thread Doc/howto/free-threading-extensions.rst
SUMMARY: ThreadSanitizer: data race racy.c:8 in bump

The TSan runtime can be configured with the ``TSAN_OPTIONS`` environment
variable, for example ``TSAN_OPTIONS="suppressions=path/to/suppressions.txt"``

@StanFromIreland StanFromIreland Nov 2, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like it belongs in https://devguide.python.org/development-tools/sanitizers/ instead, but I'll leave the decision up to the free-threading experts.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland left review comments
@erlend-aasland erlend-aasland Awaiting requested review from erlend-aasland
@AA-Turner AA-Turner Awaiting requested review from AA-Turner
@emmatyping emmatyping Awaiting requested review from emmatyping
@itamaro itamaro Awaiting requested review from itamaro
@corona10 corona10 Awaiting requested review from corona10

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@johng @corona10 @StanFromIreland
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.