classification
Title: "Thread State and the Global Interpreter Lock" section of the docs doesn't cover TLS APIs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asmodai, cheryl.sabella, exarkun, georg.brandl, iritkatriel, pitrou
Priority: normal Keywords: patch

Created on 2009-04-25 12:58 by exarkun, last changed 2021-06-20 16:49 by iritkatriel. This issue is now closed.

Files
File name Uploaded Description Edit
init.rst.diff asmodai, 2009-04-25 13:19 Remove claim we don't support TLS. review
Messages (8)
msg86501 - (view) Author: Jean-Paul Calderone (exarkun) * (Python committer) Date: 2009-04-25 12:58
Python includes several APIs for manipulating TLS:

  PyAPI_FUNC(int) PyThread_create_key(void);
  PyAPI_FUNC(void) PyThread_delete_key(int);
  PyAPI_FUNC(int) PyThread_set_key_value(int, void *);
  PyAPI_FUNC(void *) PyThread_get_key_value(int);
  PyAPI_FUNC(void) PyThread_delete_key_value(int key);

These are not covered in the threading documentation, though.  In fact,
the threading documentation goes so far as to claim that they /don't/ exist:

    While most thread packages have a way to store “per-thread global
data,” Python’s internal platform independent thread abstraction doesn’t
support this yet.

It would be great to have these APIs covered in the documentation.  One
subtlety in particular tripped me up and took a long time to track down
by reading various parts of the CPython source - when a thread exits,
its TLS values are not destroyed or reclaimed in any way.  On top of
this, the keys used by the TLS APIs are thread IDs, and thread IDs can
be re-used.  This means that a newer thread can see values from an older
thread in TLS, which was extremely surprising to me, led to a very
obscure threading bug.
msg86504 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 13:19
This is at least relevant to 2.7, reflect this in the issue.

Patch to remove the notion we don't support TLS yet.

We will need to see where to add the current functions in the overall
scheme of threading documentation.
msg86518 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-04-25 14:55
Looks good.
msg86688 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-04-27 17:10
Committed init.rst.diff in r72037.  Next step: document TLS APIs.
msg125227 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-01-03 20:16
Actually, I don't think the TLS APIs should be documented. They are quite internal, and used only for the PyGILState APIs.
msg125232 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-01-03 20:27
They are used by pyOpenSSL and pygobject/pyglib, though :/
msg312862 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-25 21:24
I believe this issue is superseded by PEP539 and issue25658?
msg396179 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-20 16:49
Indeed, this API was deprecated in 3.7:

https://docs.python.org/3/c-api/init.html#thread-local-storage-tls-api
History
Date User Action Args
2021-06-20 16:49:46iritkatrielsetstatus: open -> closed

nosy: + iritkatriel
messages: + msg396179

resolution: out of date
stage: needs patch -> resolved
2018-02-25 21:24:18cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg312862
2011-01-03 20:27:08pitrousetnosy: georg.brandl, exarkun, pitrou, asmodai
messages: + msg125232
2011-01-03 20:16:02pitrousetnosy: + pitrou
messages: + msg125227
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2009-04-27 17:10:14georg.brandlsetmessages: + msg86688
2009-04-25 14:55:19georg.brandlsetmessages: + msg86518
2009-04-25 13:19:28asmodaisetfiles: + init.rst.diff

versions: + Python 2.7
keywords: + patch
nosy: + asmodai

messages: + msg86504
stage: needs patch
2009-04-25 12:58:37exarkuncreate