gh-49960: Allow ctypes callbacks to return struct/union types

[freakboy3742]

ctypes currently prevents the definition of a callback function that returns a struct or union type.

Unfortunately, it's extremely common for C code to define a callback that returns a structure (e.g. a Point).

Rubicon-ObjC has been carrying a monkypatch for ctypes since 2017 (originally authored by @dgelessus) because there are a small number of macOS Cocoa APIs that return a struct. This PR is a formalisation of that monkey patch, in the hope that we can eventually deprecate the patch.

Based on the historical discussion on gh-49960, struct/union returns were prohibited because of the potential memory implications - a returned struct is passed by value, but if the structure contains a pointer (e.g., a string), the pointer will be copied, but the memory being referenced won't be, which could lead to unexpected results.

The patch doesn't fix that potential memory leak issue - it essentially can't in the general case. Instead, it treats the problem as a user-side issue, handled with documentation. This was the approach suggested by two of the participants on gh-49960.

The patch here is slightly different to the one used in the Rubicon monkeypatch; in Rubicon, we have to patch both getfunc and setfunc because of the residual ctypes handling. By patching the problem in CPython itself, we're able to use setfunc=None as a flag for "non-primitive return type" and use a memory copy.

Fixes #49960.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34709459 | 📁 Comparing 5894376 against main (b0dda15)

  🔍 Preview build  

2 files changed

± library/ctypes.html
± whatsnew/changelog.html