PARI’s ABI

[Ilya Zakharevich <nospam-abuse@ilyaz.org>]

The docs have a really nice section about how to work with PARI’s
stack.  However, while this documents WHAT one should do, it says
nothing about WHAT FOR are we doing this.  What is the AIM of this
exercise?

In short: I think what is missing is the description of PARI ABI: what
is expected from a PARI function, and what it may expect from its
environment.  Since I found no mention of this in the docs, I tried to
write down how I IMAGINE this ABI looks like.

   (I do not claim the description below is correct.  However, I think
    that if a CORRECT description along these lines is available in the
    docs, it may be very helpful to a developer.)

⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜ The de facto state (???) of PARI’s ABI:

A subroutine (during the call) can:
  put arbitrary data on the PARI stack;
  allocate arbitrary PARI data on the PARI heap;
  allocate arbitrary C data on the C heap;
  create arbitrary side effect (opened files etc).

  There may be “special” data on the PARI heap which references other data allocated on the PARI heap.  Freeing such data should
  be special-cased to free the referenced data as well.

⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜ On “normal” return:
  All the data allocated on the C heap and the PARI heap must be removed (unless \emph{the purpose} is to allocate something there);
  The PARI stack should be as on the entry to the subroutine, with the returned PARI data (if present) added on top;
  The returned PARI data must be as compacted as feasible (but still, it is allowed to have holes);
  The returned PARI data should (recursively) mention only PARI data on this chunk, or (???) PARI data on PARI heap;
  All the side effects (which are not the purpose of the call) should be undone.

If an exception is thrown:
  Allocated data on the PARI stack and heap (???) is supposed to be removed by whoever catches the exception;
  Allocated data on the C heap is going to leaked;
  Side effects of what the subroutine did are not going to be undone by the caller.

Changing global variables (precision, series precision)???  (With exception of functions which are designed to change them???)

⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜ On the price of things

Allocation/deallocation on the PARI stack is extremely cheap.
Allocation/deallocation on the C heap is much more expensive.
Allocation/deallocation on the PARI heap is yet slightly more expensive.

  Should there be a macro to allocate arbitrary data on PARI stack???  (Without tricks like allocating a t_INT!)

⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜ “Modified” arrays

What about arrays on the PARI heap which have been “modified” to address other data on the PARI heap?  Should not they
(and ALL their parents) be marked for deep-inspection-on-deletion???

⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜⁜ List of exceptions

Functions which break the ABI (such as gclone(), setprecision()) should be explicitly listed.

Yours,
Ilya