Define restrictions for tp_destroy functions.

[fangerer]

Rationale

Destroy functions have signature void (*tp_destroy_fun_t)(void *obj) where obj is the pointer to the native memory associated with the object to destroy.
Notably, the destroy function does also not receive an HPy context.
The (implicit) restrictions given by the signature actually suggest that the runtime would be able to execute destroy functions concurrently (without the need of acquiring the GIL).
However, as far as I know HPy does currently not specify anything concerning concurrency and in general about destroy functions. As we learned in the past, users will rely on non-specify but runtime-specific behavior.
E.g. users could rely on that the GIL is acquired when running the destroy function and thus don't need to do further synchronization.

Proposal

I propose that we should specify two important restrictions for destroy functions:

1. Destroy functions must be thread safe.
2. Destroy functions must not access the context or call into the runtime.I think these two restrictions do not make it significantly more difficult to implement destroy functions since the main purpose is to free native memory or to implement object caches.
   In case of simple freeing, there is nothing to do in addition since LibC's memory manager is thread-safe.
   In case of object caches, the C extension author needs to synchronize the cache.

[hodgestar]

Documenting these is a great idea.

At the same time we should also document how tp_destroy should be used to perform common tasks. E.g. https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_dealloc mentions calling Py_DECREF on objects referenced by the instance and calling Py_DECREF on the objects type. In HPy one wouldn't store long-term references to handles, and the context isn't available to call HPy_Close with anyway, but we should explain to people how they should modify their existing extensions and what they should do instead.

[antocuni]

I agree on documenting the restrictions. The fact that you can't call into runtime APIs is "implicit by design", that's why we don't pass a context to it. But I agree we should document it properly.
Bonus point if we find a way to detect some of the errors in debug mode (but I'm not sure it's possible).

In HPy one wouldn't store long-term references to handles, and the context isn't available to call HPy_Close with anyway, but we should explain to people how they should modify their existing extensions and what they should do instead.

yes, but before documenting that we need to implement support for HPyField :). See #9

[fangerer]

This issue is actually resolved since we describe restrictions here: https://docs.hpyproject.org/en/latest/porting-guide.html#deallocator-slot-py-tp-dealloc