Adding modifiers to NCI

[chromatic]

On Friday 26 December 2008 16:54:05 Allison Randal wrote:

> We're not using a "forty-year old mechanism for specifying the
> signatures of C functions", we're using our own custom syntax that
> includes things like the Parrot interpreter, Parrot register types,
> slurpy arrays, etc.

It misses things that existing C functions need.  It adds things that existing 
C functions don't know about and don't care about.

> Oh, wait... do you think I mean that we should eliminate NCI entirely in
> favor of PCC? No, not at all. I'm only talking about the strings
> representing the signatures.

Me too.

> Okay, quick pass conversion:
>
> # INT register stuff
> # I (same) - INTVAL

Useless for anything other than calling existing Parrot functions, unless you 
know that Parrot's INTVAL maps directly onto some sort of integer in the 
shared library -- and that's only valid for libparrots which share the same 
compile-time configuration on similar architectures.

> # c (C) - char

Signed?  Unsigned?

> # s (H) - short

Signed?  Unsigned?

> # i (T) - int

How many bits?  8?  16?  32?  64?  128?  Signed?  Unsigned?

> # l (L) - long

How many bits?  Signed?  Unsigned?  How about long long?

> # NUM register stuff
> # N (same) - FLOATVAL

Again, useful only for calling existing Parrot functions, and functionally 
useless for calling non-Parrot shared libraries.  (It *may* work in some 
cases, but parrotport.pod will rightly warn against it.)

> # f (F) - float
> # d (D) - double

How many bits?  Signed or unsigned?

> # STR register stuff
> # S (same) - pointer to a STRING-register

Useful only for calling existing Parrot functions.

> # t (C*) - character string (0-terminated)

Allocated by whom?  What's its lifespan?  Is there an associated free() 
function?

For example, you set the context of an HTTP request through libcurl by passing 
C strings to configuration functions.  These strings must persist through the 
entirety of the request.  If you (or the thunking layer) frees the C strings 
prematurely, your program will crash.

> # Buffers are not valid return parameters,
> # use 'p' when the native function returns a pointer value
> # b (V*) - void *
> # B (V**) - void **

> # PMC register stuff
> # P (same) - pointer to a PMC-register

Useful only for calling existing Parrot functions.

> # O ('Pi' for *P*MC *i*nvocant) - pointer to PMC-register (object)

Useful only for calling existing Parrot methods.

> # p (A) - data pointer from PMC (on store into a new UnManagedStruct
> PMC) [Note: generic pointer type, i.e. "pointer to *A*nything" ]

How big are pointers on this platform?

> # 2 (H*) - pointer to short
> # 3 (T*) - pointer to int
> # 4 (L*) - pointer to long

How many bits wide?  Signed or not?

> # void stuff
> # v (V) - void
>
> # special stuff
> # 0 (Z) - insert a NULL (pointer) - doesn't consume a register
> # J (same) - Parrot_Interp param

Useful

> # @ ('Ps' for *P*MC *s*lurpy) - slurpy array

C doesn't have slurpy arrays.  The closest thing it has are varargs, and you 
have to treat these very, very differently -- on some platforms you may be 
able to get by by marshalling a list of arguments in to a va_list and passing 
the resulting pointer directly, but I'm not sure how well that works across 
compilers, platforms, and C ABIs.

I also don't see any examples of out parameters.

-- c