gh-125543: Add an internal C API for dynamic arrays

Include/internal/pycore_dynarray.h

@@ -0,0 +1,233 @@
+#ifndef Py_INTERNAL_DYNARRAY_H
+#define Py_INTERNAL_DYNARRAY_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "Python.h" // Py_ssize_t
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#define _PyDynArray_DEFAULT_SIZE 16
+
+/*
+ * Deallocator for items on a _PyDynArray structure. A NULL pointer
+ * will never be given to the deallocator.
+ */
+typedef void (*_PyDynArray_Deallocator)(void *);
+
+/*
+ * Internal only dynamic array for CPython.
+ */
+typedef struct {
+    /*
+     * The actual items in the dynamic array.
+     * Don't access this field publicly to get
+     * items--use _PyDynArray_GET_ITEM() instead.
+     */
+    void **items;
+    /*
+     * The length of the actual items array allocation.
+     */
+    Py_ssize_t capacity;
+    /*
+     * The number of items in the array.
+     * Don't use this field publicly--use _PyDynArray_LENGTH()
+     */
+    Py_ssize_t length;
+    /*
+     * The deallocator, set by one of the initializer functions.
+     * This may be NULL.
+     */
+    _PyDynArray_Deallocator deallocator;
+} _PyDynArray;
+
+
+static inline void
+_PyDynArray_ASSERT_VALID(_PyDynArray *array)
+{
+    assert(array != NULL);
+    assert(array->items != NULL);
+}
+
+static inline void
+_PyDynArray_ASSERT_INDEX(_PyDynArray *array, Py_ssize_t index)
+{
+    // Ensure the index is valid
+    assert(index >= 0);
+    assert(index < array->length);
+}
+
+/*
+ * Initialize a dynamic array with an initial size and deallocator.
+ *
+ * If the deallocator is NULL, then nothing happens to items upon
+ * removal and upon array clearing.
+ *
+ * Returns -1 upon failure, 0 otherwise.
+ */
+PyAPI_FUNC(int)
+_PyDynArray_InitWithSize(_PyDynArray *array,
+                         _PyDynArray_Deallocator deallocator,
+                         Py_ssize_t initial);
+
+/*
+ * Append to the array.
+ *
+ * Returns -1 upon failure, 0 otherwise.
+ * If this fails, the deallocator is not ran on the item.
+ */
+PyAPI_FUNC(int) _PyDynArray_Append(_PyDynArray *array, void *item);
+
+/*
+ * Insert an item at the target index. The index
+ * must currently be a valid index in the array.
+ *
+ * Returns -1 upon failure, 0 otherwise.
+ * If this fails, the deallocator is not ran on the item.
+ */
+PyAPI_FUNC(int)
+_PyDynArray_Insert(_PyDynArray *array, Py_ssize_t index, void *item);
+
+
+/*
+ * Clear all the fields on the array.
+ *
+ * Note that this does *not* free the actual dynamic array
+ * structure--use _PyDynArray_Free() for that.
+ *
+ * It's safe to call _PyDynArray_Init() or InitWithSize() again
+ * on the array after calling this.
+ */
+PyAPI_FUNC(void) _PyDynArray_Clear(_PyDynArray *array);
+
+/*
+ * Set a value at index in the array.
+ *
+ * If an item already exists at the target index, the deallocator
+ * is called on it, if the array has one set.
+ *
+ * This cannot fail.
+ */
+PyAPI_FUNC(void)
+_PyDynArray_Set(_PyDynArray *array, Py_ssize_t index, void *item);
+
+/*
+ * Remove the item at the index, and call the deallocator on it (if the array
+ * has one set).
+ *
+ * This cannot fail.
+ */
+PyAPI_FUNC(void)
+_PyDynArray_Remove(_PyDynArray *array, Py_ssize_t index);
+
+/*
+ * Remove the item at the index *without* deallocating it, and
+ * return the item.
+ *
+ * This cannot fail.
+ */
+PyAPI_FUNC(void *)
+_PyDynArray_Pop(_PyDynArray *array, Py_ssize_t index);
+
+/*
+ * Clear all the fields on a dynamic array, and then
+ * free the dynamic array structure itself.
+ *
+ * The array must have been created by _PyDynArray_New()
+ */
+static inline void
+_PyDynArray_Free(_PyDynArray *array)
+{
+    _PyDynArray_ASSERT_VALID(array);
+    _PyDynArray_Clear(array);
+    PyMem_RawFree(array);
+}
+
+/*
+ * Equivalent to _PyDynArray_InitWithSize() with a default size of 16.
+ *
+ * Returns -1 upon failure, 0 otherwise.
+ */
+static inline int
+_PyDynArray_Init(_PyDynArray *array, _PyDynArray_Deallocator deallocator)
+{
+    return _PyDynArray_InitWithSize(array, deallocator, _PyDynArray_DEFAULT_SIZE);
+}
+
+/*
+ * Allocate and create a new dynamic array on the heap.
+ *
+ * The returned pointer should be freed with _PyDynArray_Free()
+ * If this function fails, it returns NULL.
+ */
+static inline _PyDynArray *
+_PyDynArray_NewWithSize(_PyDynArray_Deallocator deallocator, Py_ssize_t initial)
+{
+    _PyDynArray *array = PyMem_RawMalloc(sizeof(_PyDynArray));
+    if (array == NULL)
+    {
+        return NULL;
+    }
+
+    if (_PyDynArray_InitWithSize(array, deallocator, initial) < 0)
+    {
+        PyMem_RawFree(array);
+        return NULL;
+    }
+
+    _PyDynArray_ASSERT_VALID(array); // Sanity check
+    return array;
+}
+
+/*
+ * Equivalent to _PyDynArray_NewWithSize() with a size of 16.
+ *
+ * The returned array must be freed with _PyDynArray_Free().
+ * Returns NULL on failure.
+ */
+static inline _PyDynArray *
+_PyDynArray_New(_PyDynArray_Deallocator deallocator)
+{
+    return _PyDynArray_NewWithSize(deallocator, _PyDynArray_DEFAULT_SIZE);
+}
+
+/*
+ * Get an item from the array. This cannot fail.
+ *
+ * If the index is not valid, this is undefined behavior.
+ */
+static inline void *
+_PyDynArray_GET_ITEM(_PyDynArray *array, Py_ssize_t index)
+{
+    _PyDynArray_ASSERT_VALID(array);
+    _PyDynArray_ASSERT_INDEX(array, index);
+    return array->items[index];
+}
+
+/*
+ * Get the length of the array. This cannot fail.
+ */
+static inline Py_ssize_t
+_PyDynArray_LENGTH(_PyDynArray *array)
+{
+    _PyDynArray_ASSERT_VALID(array);
+    return array->length;
+}
+
+/*
+ * Pop the item at the end the array.
+ * This function cannot fail.
+ */
+static inline void *
+_PyDynArray_PopTop(_PyDynArray *array)
+{
+    return _PyDynArray_Pop(array, _PyDynArray_LENGTH(array) - 1);
+}
+
+#ifdef __cplusplus
+}
+#endif
+#endif   /* !Py_INTERNAL_DYNARRAY_H */

Makefile.pre.in

@@ -435,6 +435,7 @@ PYTHON_OBJS=	\
 		Python/critical_section.o \
 		Python/crossinterp.o \
 		Python/dynamic_annotations.o \
+		Python/dynarray.o \
 		Python/errors.o \
 		Python/flowgraph.o \
 		Python/frame.o \
@@ -1197,6 +1198,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/internal/pycore_dict.h \
 		$(srcdir)/Include/internal/pycore_dict_state.h \
 		$(srcdir)/Include/internal/pycore_dtoa.h \
+		$(srcdir)/Include/internal/pycore_dynarray.h \
 		$(srcdir)/Include/internal/pycore_exceptions.h \
 		$(srcdir)/Include/internal/pycore_faulthandler.h \
 		$(srcdir)/Include/internal/pycore_fileutils.h \