We need unambiguous, meaningful naming of stack reference operations dependent on how counting is done
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Python
- Estrellas
- 77.2k
- Forks
- 36k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
https://github.com/faster-cpython/ideas/issues/700 describes three ways to count references:
- Virtual,
- Embedded, and
- Immediate
Virtual references are references that are know to exist to the relevant code generator, but are elided at runtime, so no API is needed for them.
Embedded references are marked by bit(s) in the reference and not in the ob_refcount field of the object.
Immediate references are counted in the ob_refcount (or free-threading equivalent) field of the object.
To this we should add uncounted which are references to immortal objects (including NULL).
Note that it is possible to have embedded or immediate references to immortal objects if the object was mortal when the reference, or reference this reference was created from, was created.
Why this matters
It is important that the use of references is understandable without referring to the implementation and we have multiple implementations of stackrefs, so the interface needs to be clear.
Multiple implementations
Even when we merge the free-threading and default implementations of stackrefs, we will still have the Py_STACKREF_DEBUG implementation which is very different and vital to finding reference errors.
Examples:
When creating an embedded stackref from another stackref, we should use PyStackRef_DUP_Embedded which has the same semantics as PyStackRef_DUP but creates an embedded reference if the implementation supports it.
There are circumstance when a method of counting is not safe. E.g. using embedded references in the heap is not safe. For that we will want to physically transform a reference without a logic change in ownership.
E.g. PyStackRef_ToNonEmbedded. In terms of ownership, this a no-op, PyStackRef_ToNonEmbedded(ref) is equivalent ref, but ensures that any embedded count is turned into an immediate count.
We probably should only use uncounted when referring to references in docs and comments, as we already have PyStackRef_FromPyObjectImmortal, there is no need for PyStackRef_FromPyObjectUncounted as well.
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
El issue no menciona archivos ni tests, así que primero localiza las APIs de referencias de pila y compara sus implementaciones existentes, incluida la implementación de depuración. Revisa la terminología propuesta para Virtual, Embedded, Immediate y uncounted, así como ejemplos como PyStackRef_DUP_Embedded y PyStackRef_ToNonEmbedded. El trabajo está terminado cuando las operaciones tienen nombres inequívocos y sus semánticas de propiedad y conteo están claras en todas las implementaciones.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python
- Área
- backend
- Tipo de issue
- Refactorización
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Estancado
- Claridad
- Bastante claro
- Aptitud para principiantes
- 35/100