bpo-40428: Remove PyTuple_ClearFreeList() function

[vstinner]

Remove the following function from the C API:

• PyAsyncGen_ClearFreeLists()
• PyContext_ClearFreeList()
• PyDict_ClearFreeList()
• PyFloat_ClearFreeList()
• PyFrame_ClearFreeList()
• PyList_ClearFreeList()
• PySet_ClearFreeList()
• PyTuple_ClearFreeList()

Make these functions private, move them to the internal C API and
change their return type to void.

Call explicitly PyGC_Collect() to free all free lists.

Note: PySet_ClearFreeList() did nothing.

https://bugs.python.org/issue40428

[vstinner]

The Windows 64 job of Azure Pipelines PR fails to build Python because it failed to fetch bzip2:

Fetching bzip2-1.0.6...
(...)
  File "C:\hostedtoolcache\windows\Python\3.8.2\x64\lib\http\client.py", line 915, in connect
    self.sock = self._create_connection(
  File "C:\hostedtoolcache\windows\Python\3.8.2\x64\lib\socket.py", line 787, in create_connection
    for res in getaddrinfo(host, port, 0, SOCK_STREAM):
  File "C:\hostedtoolcache\windows\Python\3.8.2\x64\lib\socket.py", line 918, in getaddrinfo
    for res in _socket.getaddrinfo(host, port, family, type, proto, flags):
socket.gaierror: [Errno 11001] getaddrinfo failed
(...)
  File "C:\hostedtoolcache\windows\Python\3.8.2\x64\lib\urllib\request.py", line 1362, in https_open
    return self.do_open(http.client.HTTPSConnection, req,
  File "C:\hostedtoolcache\windows\Python\3.8.2\x64\lib\urllib\request.py", line 1322, in do_open
    raise URLError(err)
urllib.error.URLError: <urlopen error [Errno 11001] getaddrinfo failed>
(...)
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\blocksort.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\bzlib.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\compress.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\crctable.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\decompress.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\huffman.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]
c1 : fatal error C1083: Cannot open source file: 'd:\a\1\b\externals\bzip2-1.0.6\randtable.c': No such file or directory [D:\a\1\s\PCbuild\_bz2.vcxproj]

[aeros]

I have a bit of post-commit feedback on the wording of the whatsnew entry. If you think it could be worthwhile to address, I'll open a separate PR.

[aeros]

In the sentence "Call :c:func:PyGC_Collect explicitly to free all free lists", "free all free lists" (although technically correct) is not especially clear without the context of how the GC works. If one reads it literally, they may wonder "why would you need to explicitly free lists that are already free?".

If my own understanding is correct, I think it might make it a bit more clear if we were to instead use "immediately deallocate all free lists". It doesn't go into detail, which wouldn't make sense here, but I think it's less ambiguous. IMO, it also reads better than "free all free lists".

[aeros]

Also, as a more minor grammar fix, the second sentence could be started with "Instead, ", as in "Instead, call :c:func:PyGC_Collect explicitly to free all free lists." . If the above isn't worthwhile though, I don't think that would be worth a PR on its own.

[vstinner]

The best would be to document PyGC_Collect()... but currently, this function is not documented in Doc/c-api/ !

"why would you need to explicitly free lists that are already free?".

Is "Call PyGC_Collect() explicitly to clear all free lists." better?

[vstinner]

Feel free to propose a PR to enhance What's New In Python 3.9. English is not my first language ;-)

[aeros]

@vstinner

Is "Call PyGC_Collect() explicitly to clear all free lists." better?

Yeah, that's definitely an improvement.

Feel free to propose a PR to enhance What's New In Python 3.9. English is not my first language ;-)

Sounds good, will do. I might also look into documenting PyGC_Collect(), but I'll likely require some feedback since the C-API isn't my area of expertise. Would you mind if I requested your review on it to make sure it's correct from a technical perspective?

Also, I think you have good English skills, especially for a non-native speaker! As a native speaker who's had to go through several college English courses though, I'm glad to help where I can with the documentation; similarly to how I'd ask you or others for help w/ the C-API. :-)

[vstinner]

I created PR #19793 to group other C API changes related to free lists. I replace "free" with "clear" there ;-)

[aeros]

@vstinner Thanks for the update. I was about to work on it tomorrow otherwise, just finishing up my finals for the semester. :-)

I still plan on looking into documenting PyGC_Collect, but I need to more closely analyze the implementation and existing docstring first to make sure I get the details right. I'll open a PR and request a review when it's ready (if that's okay).

[vstinner]

I still plan on looking into documenting PyGC_Collect, but I need to more closely analyze the implementation and existing docstring first to make sure I get the details right. I'll open a PR and request a review when it's ready (if that's okay).

Well, there is an easy way to document PyGC_Collect: it's similar to the Python gc.collect() (called without arguments), except that PyGC_Collect() does nothing if the GC is disabled.