mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-03 13:45:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Adjust stable ABI internal documentation (GH-96896)

Browse source 
I was perusing this file, and noticed that this part of the documentation is slightly out of date: the `struct` items in this TOML file currently contain `struct_abi_kind` members, which distinguish between the different types of ABI compatibility described in the comment.

I've updated the comment to reflect this.
(cherry picked from commit 6e53308829)

Co-authored-by: William Woodruff <william@yossarian.net>
This commit is contained in:
Miss Islington (bot) 2022-10-04 06:15:46 -07:00 • committed by Pablo Galindo
parent e232e49e86
commit 746fb3c91d
No known key found for this signature in database
GPG key ID: FFE87404168BD847
1 changed files with 14 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

21
Misc/stable_abi.toml
View file

@ -13,13 +13,8 @@
# The current format is TOML. # The current format is TOML.
# There are these kinds of top-level "items": # There are these kinds of top-level "items":
# - struct: A C struct. Currently this file does not distinguish between: # - struct: A C struct. See `struct_abi_kind` for how much of the struct is
# - opaque structs, which the Limited API only handles via pointers # exposed.
# (so these can change at any time)
# - structs where only certain members are part of the stable ABI (e.g.
# PyObject)
# - structs which must not be changed at all (e.g. PyType_Slot, which is
# fully defined and used in arrays)
# - function: A function that must be kept available (and exported, i.e. not # - function: A function that must be kept available (and exported, i.e. not
# converted to a macro). # converted to a macro).
# - const: A simple value, defined with `#define`. # - const: A simple value, defined with `#define`.
@ -42,6 +37,18 @@
# of the stable ABI. # of the stable ABI.
# - a combination of the above (functions that were called by macros that # - a combination of the above (functions that were called by macros that
# were public in the past) # were public in the past)
# - struct_abi_kind: for `struct`, defines how much of the struct is exposed:
# - 'full-abi': All of the struct is part of the ABI, including the size
# (users may define arrays of these structs).
# Typically used for initalization, rather than at runtime.
# - 'opaque': No members are part of the ABI, nor is the size. The Limited
# API only handles these via pointers. The C definition should be
# incomplete (opaque).
# - 'members': Only specific members are part of the stable ABI.
# The struct's size may change, so it can't be used in arrays.
# Do not add new structs of this kind without an extremely good reason.
# - members: For `struct` with struct_abi_kind = 'members', a list of the
# exposed members.
# - doc: for `feature_macro`, the blurb added in documentation # - doc: for `feature_macro`, the blurb added in documentation
# - windows: for `feature_macro`, this macro is defined on Windows. # - windows: for `feature_macro`, this macro is defined on Windows.
# (This info is used to generate the DLL manifest and needs to be available # (This info is used to generate the DLL manifest and needs to be available