Add "unstable" frame stack api

[markshannon]

BPO	47215
Nosy	@markshannon, @brandtbucher
PRs	bpo-47215: Add undocumented, unstable FrameStack API for use by greenlets and similar libraries. #32303

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/markshannon'
closed_at = None
created_at = <Date 2022-04-04.11:59:07.553>
labels = ['expert-C-API', 'type-feature', '3.11']
title = 'Add "unstable" frame stack api'
updated_at = <Date 2022-04-04.12:09:47.075>
user = 'https://github.com/markshannon'

bugs.python.org fields:

activity = <Date 2022-04-04.12:09:47.075>
actor = 'Mark.Shannon'
assignee = 'Mark.Shannon'
closed = False
closed_date = None
closer = None
components = ['C API']
creation = <Date 2022-04-04.11:59:07.553>
creator = 'Mark.Shannon'
dependencies = []
files = []
hgrepos = []
issue_num = 47215
keywords = ['patch']
message_count = 1.0
messages = ['416665']
nosy_count = 2.0
nosy_names = ['Mark.Shannon', 'brandtbucher']
pr_nums = ['32303']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue47215'
versions = ['Python 3.11']

Linked PRs

• WIP: gh-91371: Add PyFrameStack C API #119596

[markshannon]

We need to provide an API to create, swap and free frame stacks for greenlets.

Since this is primarily for greenlets (and any other stackful coroutines libraries that want to use it) it will be "unstable".

In this case, by "unstable" I mean:

1. Starts with an underscore
2. Gets PyAPI_FUNC annotations, so we don't strip the symbols from the executable
3. Undocumented, except for comments that say it is unstable.

The API will be:

typedef struct _frame_stack {
 _PyStackChunk *current_chunk;
 PyObject **top;
 PyObject **limit;
 int chunk_size;
} _PyFrameStack;

PyAPI_FUNC(void) _PyFrameStack_Init(_PyFrameStack *fs, int chunk_size);
PyAPI_FUNC(void) _PyFrameStack_Swap(_PyFrameStack *fs);
PyAPI_FUNC(void) _PyFrameStack_Free(_PyFrameStack *fs);

[vstinner]

greenlet code to save the Python thread state (C++): https://github.com/python-greenlet/greenlet/blob/937f150e07823ee03344aeeb5111c0bb371a831d/src/greenlet/TPythonState.cpp#L111

greenlet is used by eventlet and gevent projects.

PyOdide has similar code (in C): https://github.com/pyodide/pyodide/blob/d317e66d174efa203c59f094eb7714c0b90f7613/src/core/stack_switching/pystate.c#L161-L187

[vstinner]

cc @hoodmane