Re: ffi docs

[Neil Jerram]

Andy Wingo <address@hidden> writes:

> Hi,
>
> Thanks for the feedback!

Thanks for the quick responses.  As far as most of them are concerned,
I'll read the section on foreign functions first before offering more
thoughts, as you suggest.  Also I agree that it will make sense for me
to handle these doc changes.

On a couple of specific points....

> On Fri 16 Apr 2010 00:36, Neil Jerram <address@hidden> writes:
>
>>>    But yet we as programmers live in both worlds, and Guile itself is
>>> half implemented in C. So it is that Guile's living half pays respect
>>> to its dead counterpart, via a spectrum of interfaces to C ranging from
>>> dynamic loading of Scheme primitives to dynamic binding of stock C
>>> library prodedures.
>>
>> c -----------^
>
> What does this mean?

I'm sorry!  It was supposed to indicate a typo, and that there should be
a "c" at the place the caret points - i.e. "procedures" rather than
"prodedures".  Anyway, I'll handle this.

>>>    We titled this section "foreign libraries" because although the name
>>> "foreign" doesn't leak into the API, the world of C really is foreign
>>> to Scheme - and that estrangement extends to components of foreign
>>> libraries as well, as we see in future sections.
>>
>> I'm not sure what the message is here.
>
> Probably me being to cutesy, I would imagine.

I didn't think that!

> The facility is typically
> called a "foreign function interface", but that name doesn't appear in
> e.g. "dynamic-link", so I was trying to explain.

Ah yes, I see now.  In that case I think it's just the last clause that
doesn't quite work for me.  I would say that the _immediately_ following
text is about "components of foreign libraries", so why say "as we see
in future sections"?

Maybe: "... really is foreign to Scheme.  Foreign function and data
pointers, obtained via `dynamic-func' and `dynamic-pointer', or as
return values from a foreign function call, are inherently untyped, and
depend on the Scheme programmer using them in a way that is consistent
with the library's documented interface.  Any other usage is unsafe and
can easily cause the containing Scheme program to crash, and the Guile
low-level FFI cannot protect against this.  (This is quite different
from computations on Scheme values; Scheme values are typed, and so
operations on them can check in advance that the value types are as
expected.)"

>> Code below implies that library can be omitted, and that this -
>> i.e. '(dynamic-link)' - means to return an object representing libguile
>> itself.  Should that be mentioned in the following doc?
>>
>>>      Find the shared library denoted by LIBRARY (a string) and link it
>>>      into the running Guile application.  When everything works out,
>>>      return a Scheme object suitable for representing the linked object
>>>      file.  Otherwise an error is thrown.  How object files are
>>>      searched is system dependent.
>>>
>>>      Normally, LIBRARY is just the name of some shared library file
>>>      that will be searched for in the places where shared libraries
>>>      usually reside, such as in `/usr/lib' and `/usr/local/lib'.
>>>
>>>      When LIBRARY is omitted, a "global symbol handle" is returned.
>>>      This handle provides access to the symbols available to the
>>>      program at run-time, including those exported by the program
>>>      itself and the shared libraries already loaded.
>
> I think it is mentioned, no? Is there a way that it can be more clear?

I'm sorry.  I can't believe I missed that.  I looked for it so
carefully!

>> - isn't it actually much more to do with the ELF binary format, rather
>>   than with C?  If libguile could read and parse C, it would be able to
>>   infer the type of any variable that the Scheme layer might request.
>>   The problem is precisely that what we are linking with is *not* C
>>   anymore...  It's just untyped pointers.
>
> I guess you're right, this is confusing. C doesn't really exist at
> runtime, and this API is all about accessing runtime values.

On further reflection, I think I'm not completely right.  Functions
assume that they will be called according to well known C calling
conventions.  So I guess there are vestiges of C.

Out of interest, do other languages that compile to library format use
different calling conventions, and if so can dlopen/dlsym and FFIs work
with them?

More tomorrow...

Regards,
      Neil