RFR: 7903209: Handle lifecycle of libclang abstractions more explicitly

[Maurizio Cimadamore]

On Fri, 10 Jun 2022 21:44:06 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch clarifies the lifecycle of the entities generated by jextract. The main changes are two:
> 
> 1. First, instead of "buffering" cursors in the `Cursor.children` method, so that a `Stream` can be returned, it instead accepts an action which will be executed for each visited cursor. This allows us to get rid of the buffering code, but at the same time it means that the downstream code has to be careful: any attempt to cache the cursor into a field, and access it _after_ the visitor has completed wil result in issues.
> 
> 2. Secondly, it replaces uses of implicit session and implicit allocator almost everywhere. There are two main lifecycle entities: index and translation unit (there are others too, but these are the main ones). Translation units are created inside an index lifetime, whereas cursors and types are created inside the translation unit lifetime. This patch makes this organization clear, by adding a new type called `ClangDisposable`, an entity that has a session, and an associated arena allocator - and an `Owned` an entity that is owned by some `ClangDisposable` (and so it can use its arena to perform allocation). This scheme is relatively simple, but at the same time quite expressive, and helps keeping the complexity in check.
> 
> As a result, most of the allocation now occurs in a confined scope, with clear lifetime boundaries. Any  attemp to access e.g. a cursor after its translation unit is gone will result in an exception. I believe this can be quite useful to catch latent lifecycle issues in the code (I already fixed a few when working on this patch).

Overall, I think this exercise highlighted some areas of improvement for the FFM API:
* we need some mechanism like dependent sessions [1], to express nested lifetimes
* the upcall machinery needs some extra flexibility - such as the ability of creating JNI handles from heap objects (so that we can pass custom Java objects to native visitors) - or some equivalent functionality
* handling exceptions in upcalls is also a bit strange - but not sure we can do much here - the fact that we need to cache pending exception seems bad though. Note that in this case it means we need to update some field in a static context.

[1] - https://inside.java/2021/10/12/panama-scope-dependencies/

-------------

PR: https://git.openjdk.org/jextract/pull/48