Guile API for foreign languages: proposing SCM scm_list_0(void)

Guile API for foreign languages: proposing SCM scm_list_0(void)

[Alexei Matveev]

Quote from

http://lists.gnu.org/archive/html/guile-devel/2001-06/msg00348.html

>> Do we want scm_list_0 to scm_list_9 anyway?
>
> I'd say, forget about scm_list_0.  With respect to the others, we should
> at least provide those which are used in libguile (egoistic point of
> view, isn't it?).  About the rest up to 9 I don't know/mind.

Hi, All,

To raise this question again: I ended up with a wrapper
function for a Fortran project equivalent to the scm_list_0()
quoted below. The reason is accessing macros from languages
other than C is cumbersome.

Contrary to scm_from/to_int, scm_is_*  and other macros
adding this as a funciton one is a no-brainer, since it would
be a new API call and raises no compatibility concerns.

What do you think? Do you count from 0 or from 1?

Alexei

P.S.: the next on my which list would be scm_undefined().

$ git diff libguile/list.c
diff --git a/libguile/list.c b/libguile/list.c
index 8297b17..e253510 100644
--- a/libguile/list.c
+++ b/libguile/list.c
@@ -41,6 +41,12 @@
   } while (0)

 SCM
+scm_list_0 ()
+{
+  return SCM_EOL; /* macro */
+}
+
+SCM
 scm_list_1 (SCM e1)
 {
   SCM c1;

Re: Guile API for foreign languages: proposing SCM scm_list_0(void)

[Andy Wingo]

Hi Alexei,

On Mon 02 Jul 2012 13:11, Alexei Matveev <alexei.matveev@gmail.com> writes:

> To raise this question again: I ended up with a wrapper
> function for a Fortran project equivalent to the scm_list_0()
> quoted below. The reason is accessing macros from languages
> other than C is cumbersome.
>
> Contrary to scm_from/to_int, scm_is_*  and other macros
> adding this as a funciton one is a no-brainer, since it would
> be a new API call and raises no compatibility concerns.

Apologies for ignoring you.  I think that the thought that if we wanted
to follow through the logic of making Guile's C API available to non-C
languages, we should do so either all the way or not at all.

Each additional function added to Guile's ABI imposes additional cost in
runtime memory, ELF symbol resolution, and (to a degree) startup time,
without providing any benefits to C users.  On the other hand, if we are
only talking about 2 functions (say), then clearly we should do it.  So
part of the question is, how much work are we talking about?

I grepped the header files for lines starting with "#define SCM_",
munged out the name of the macro and sorted them for uniqueness.  That
was around 1200 macros.  I filtered out certain kinds of macros:

  * those ending in _H (header guards)
  * those starting with SCM_I_ (internal macros)
  * those containing _BIT (implementation details)
  * SCM_VALIDATE_ macros (there are corresponding C procedures)

That left me with about 900 macros.

I then filtered out all macros that had a corresponding C binding.  For
example, SCM_CAR has a C procedure, `scm_car'.  That left me with about
780 macros.

Finally, from this list, I filtered out those symbols that did not
appear in our documentation.  That resulted in the following 77 symbols:

    SCM_ALLOW_INTS
    SCM_ARG1
    SCM_ARG2
    SCM_ARG3
    SCM_ARG4
    SCM_ARG5
    SCM_ARG6
    SCM_ARG7
    SCM_ARGn
    SCM_ASSERT_TYPE
    SCM_BOOL_F
    SCM_BOOL_T
    SCM_BYTEVECTOR_CONTENTS
    SCM_CELL_OBJECT
    SCM_CELL_OBJECT_0
    SCM_CELL_OBJECT_1
    SCM_CELL_TYPE
    SCM_CELL_WORD
    SCM_CELL_WORD_0
    SCM_CELL_WORD_1
    SCM_DEFER_INTS
    SCM_ELISP_NIL
    SCM_EOF_VAL
    SCM_EOL
    SCM_FRAME_DATA_ADDRESS
    SCM_FRAME_LOWER_ADDRESS
    SCM_FRAME_UPPER_ADDRESS
    SCM_GLOBAL_KEYWORD
    SCM_GLOBAL_VARIABLE
    SCM_GLOBAL_VARIABLE_INIT
    SCM_GPROC
    SCM_HOOKP
    SCM_IMP
    SCM_NEWSMOB
    SCM_NEWSMOB2
    SCM_NEWSMOB3
    SCM_PTAB_ENTRY
    SCM_PTOBNUM
    SCM_REGISTER_PROC
    SCM_RETURN_NEWSMOB
    SCM_RETURN_NEWSMOB2
    SCM_RETURN_NEWSMOB3
    SCM_SET_CELL_OBJECT
    SCM_SET_CELL_OBJECT_0
    SCM_SET_CELL_OBJECT_1
    SCM_SET_CELL_TYPE
    SCM_SET_CELL_WORD
    SCM_SET_CELL_WORD_0
    SCM_SET_CELL_WORD_1
    SCM_SET_SMOB_DATA
    SCM_SET_SMOB_DATA_2
    SCM_SET_SMOB_DATA_3
    SCM_SET_SMOB_FLAGS
    SCM_SET_SMOB_OBJECT
    SCM_SET_SMOB_OBJECT_2
    SCM_SET_SMOB_OBJECT_3
    SCM_SIMPLE_VECTOR_LENGTH
    SCM_SIMPLE_VECTOR_REF
    SCM_SIMPLE_VECTOR_SET
    SCM_SMOB_DATA
    SCM_SMOB_DATA_2
    SCM_SMOB_DATA_3
    SCM_SMOB_FLAGS
    SCM_SMOB_OBJECT
    SCM_SMOB_OBJECT_2
    SCM_SMOB_OBJECT_2_LOC
    SCM_SMOB_OBJECT_3
    SCM_SMOB_OBJECT_3_LOC
    SCM_SMOB_OBJECT_LOC
    SCM_SMOB_PREDICATE
    SCM_TICK
    SCM_UNBNDP
    SCM_UNBOUND
    SCM_UNDEFINED
    SCM_UNSPECIFIED
    SCM_VARIABLE_INIT

The next step would be to manually check which of these symbols are
actually necessary.  Perhaps I can leave this job to someone else :)

Regards,

Andy
-- 
http://wingolog.org/

Re: Guile API for foreign languages: proposing SCM scm_list_0(void)

[Alexei Matveev]

>> The reason is accessing macros from languages
>> other than C is cumbersome.
>
> Apologies for ignoring you.

Hi, Wingo, Hi, All,

No need to apologise, given your track record I trust you spending
every minute of your time for a good purpose. :)
Lack of time is a good evolutionary filter against worthless proposals.

> I think that the thought that if we wanted
> to follow through the logic of making Guile's C API available to non-C
> languages, we should do so either all the way or not at all.

This does not need to be a full Guile API, but rather a "Scheme"
API --- the necessary minimum to "write Scheme in a foreign language".
A language may be assumed to be C-interoperable, though macros should
not be part of this interoperability.

> Each additional function added to Guile's ABI imposes additional cost in
> runtime memory, ELF symbol resolution, and (to a degree) startup time,
> without providing any benefits to C users.  On the other hand, if we are
> only talking about 2 functions (say), then clearly we should do it.  So
> part of the question is, how much work are we talking about?

Another valid reason to distinguish Guile and "Scheme" APIs.

> I grepped the header files for lines starting with "#define SCM_",
> munged out the name of the macro and sorted them for uniqueness.  That
> was around 1200 macros.  I filtered out certain kinds of macros:
>
>   * those ending in _H (header guards)
>   * those starting with SCM_I_ (internal macros)
>   * those containing _BIT (implementation details)
>   * SCM_VALIDATE_ macros (there are corresponding C procedures)
>
> That left me with about 900 macros.
>
> I then filtered out all macros that had a corresponding C binding.  For
> example, SCM_CAR has a C procedure, `scm_car'.  That left me with about
> 780 macros.
>
> Finally, from this list, I filtered out those symbols that did not
> appear in our documentation.  That resulted in the following 77 symbols:

Thanks for a serious analysis. However there appear also to be some  lower
case scm_* macros documented as an API. Here  are those that  I had  to
"add to  API as functions"  in my case:

  scm_to_int();
  scm_is_true();
  scm_is_symbol();
  scm_is_null();

These may be the  real showstoppers. Someone on the  list (or IRC) told
me adding  them as functions may  result in  a problem. Or  was that
"redefining them as functions"?

I must confess that I never compiled Guile myself, so I am in no way
qualified ehough  to classify all the SCM_* macros left after your filtering,
but let me start.

The first group of a few constants contains those that are mentioned in
the Scheme standard. Most of them may be obtained as a return value by
calling  that or  another function.   A  global (linker)  symbol or  a
dedicated "constructor" may be  more convinient in some situations for
foreign bindings:

    SCM_BOOL_F          #f

    SCM_BOOL_T          #t

    SCM_EOL             '()

    SCM_UNDEFINED       "something  that  when  stored in  a  location
                        makes it  an error to try to  obtain the value
                        stored in the  location (no such expression is
                        defined in Scheme)"

    SCM_UNSPECIFIED     (if #f #f)

    SCM_EOF_VAL         (with-input-from-string "" read)

Not so sure about the next  two predicates.  They do not have a Scheme
counterpart, but appear to  be an important implementation detail for
functions of  variable arity (I  guess).  There appears to  be already
some redundancy/confusion, at least for me [1]:

    SCM_UNBNDP
    SCM_UNBOUND

The rest  below should not be  required to "write scheme  in a foreign
language",  but  rather  to  extend  Scheme.  Other  macros,  such  as
SCM_GLOBAL_VARIABLE_INIT,  and snarfing  magic are  convenience macros
for C  programs and do not  necessarily need to have  a counterpart in
other bindings:

    SCM_ALLOW_INTS
    SCM_ARG1
    SCM_ARG2
    SCM_ARG3
    SCM_ARG4
    SCM_ARG5
    SCM_ARG6
    SCM_ARG7
    SCM_ARGn
    SCM_ASSERT_TYPE
    SCM_BYTEVECTOR_CONTENTS
    SCM_CELL_OBJECT
    SCM_CELL_OBJECT_0
    SCM_CELL_OBJECT_1
    SCM_CELL_TYPE
    SCM_CELL_WORD
    SCM_CELL_WORD_0
    SCM_CELL_WORD_1
    SCM_DEFER_INTS
    SCM_ELISP_NIL
    SCM_FRAME_DATA_ADDRESS
    SCM_FRAME_LOWER_ADDRESS
    SCM_FRAME_UPPER_ADDRESS
    SCM_GLOBAL_KEYWORD
    SCM_GLOBAL_VARIABLE
    SCM_GLOBAL_VARIABLE_INIT
    SCM_GPROC
    SCM_HOOKP
    SCM_IMP
    SCM_NEWSMOB
    SCM_NEWSMOB2
    SCM_NEWSMOB3
    SCM_PTAB_ENTRY
    SCM_PTOBNUM
    SCM_REGISTER_PROC
    SCM_RETURN_NEWSMOB
    SCM_RETURN_NEWSMOB2
    SCM_RETURN_NEWSMOB3
    SCM_SET_CELL_OBJECT
    SCM_SET_CELL_OBJECT_0
    SCM_SET_CELL_OBJECT_1
    SCM_SET_CELL_TYPE
    SCM_SET_CELL_WORD
    SCM_SET_CELL_WORD_0
    SCM_SET_CELL_WORD_1
    SCM_SET_SMOB_DATA
    SCM_SET_SMOB_DATA_2
    SCM_SET_SMOB_DATA_3
    SCM_SET_SMOB_FLAGS
    SCM_SET_SMOB_OBJECT
    SCM_SET_SMOB_OBJECT_2
    SCM_SET_SMOB_OBJECT_3
    SCM_SIMPLE_VECTOR_LENGTH
    SCM_SIMPLE_VECTOR_REF
    SCM_SIMPLE_VECTOR_SET
    SCM_SMOB_DATA
    SCM_SMOB_DATA_2
    SCM_SMOB_DATA_3
    SCM_SMOB_FLAGS
    SCM_SMOB_OBJECT
    SCM_SMOB_OBJECT_2
    SCM_SMOB_OBJECT_2_LOC
    SCM_SMOB_OBJECT_3
    SCM_SMOB_OBJECT_3_LOC
    SCM_SMOB_OBJECT_LOC
    SCM_SMOB_PREDICATE
    SCM_TICK
    SCM_VARIABLE_INIT

Alexei

[1] http://www.sourceware.org/ml/guile/2000-03/msg00618.html

Re: Guile API for foreign languages: proposing SCM scm_list_0(void)

[Andy Wingo]

On Mon 14 Jan 2013 23:44, Alexei Matveev <alexei.matveev@gmail.com> writes:

>   scm_to_int();
>   scm_is_true();
>   scm_is_symbol();
>   scm_is_null();

We can change these to inline functions, no problem.  They would also
get an out-of-line version written to the .so, so that should work for
you too.

It seems that we can indeed make all of our API available to non-C
users.  Any objections to doing so?

Andy
-- 
http://wingolog.org/

Re: Guile API for foreign languages: proposing SCM scm_list_0(void)

[Ludovic Courtès]

Hi!

Andy Wingo <wingo@pobox.com> skribis:

> On Mon 14 Jan 2013 23:44, Alexei Matveev <alexei.matveev@gmail.com> writes:
>
>>   scm_to_int();
>>   scm_is_true();
>>   scm_is_symbol();
>>   scm_is_null();
>
> We can change these to inline functions, no problem.  They would also
> get an out-of-line version written to the .so, so that should work for
> you too.
>
> It seems that we can indeed make all of our API available to non-C
> users.  Any objections to doing so?

You wrote:

> Each additional function added to Guile's ABI imposes additional cost in
> runtime memory, ELF symbol resolution, and (to a degree) startup time,
> without providing any benefits to C users.  On the other hand, if we are
> only talking about 2 functions (say), then clearly we should do it.  So
> part of the question is, how much work are we talking about?

So I agree: if we’re talking about a few functions, that’s fine;
otherwise, that may be questionable.

WDYT?

Thanks,
Ludo’.