Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Doug Evans]

On Sun, Apr 27, 2014 at 6:17 AM, Andy Wingo <wingo@pobox.com> wrote:
> Hi,
>
> SMOBs have a few problems.
>
> [...]
>   7) There is legacy code out there that uses e.g. SCM_SETCDR to set
>      smob fields.  (This is terrible, but it exists:
>      https://github.com/search?q=SCM_SETCDR+smob&ref=cmdform&type=Code
>      for an example.)

Hi.
While it's on my mind I thought I'd write it down.

While function declarations are markable as being internal/external in
published headers (SCM_INTERNAL vs SCM_API), macros are not.
IWBN to solve this problem for macros too.  If it's in a header and a
user can get it to work, s/he may just use it - some macros are indeed
usable, so how does one easily know while reading headers (users will
do that a lot) which are legitimately usable and which are not?

There are various ways to solve this, I don't have a strong opinion on
that, but IWBN to solve it.
Setting aside moving internal things to separate headers (which feels
more expensive than it's worth), one could just wrap them in
appropriate #ifs.

[P.S. I'm not sure if SCM_SETCDR is still intended to be usable, I
wouldn't mind deprecating it, and only publishing the function
versions.  I can imagine it being ubiquitous enough in existing code
that that's not possible, even if one wanted to.  At any rate that's a
separate discussion.  Its presence in the foreign object discussion
just reminded me of macros in headers.]

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Andy Wingo]

Hi!

On Tue 29 Apr 2014 18:33, Doug Evans <xdje42@gmail.com> writes:

> On Sun, Apr 27, 2014 at 6:17 AM, Andy Wingo <wingo@pobox.com> wrote:
>>
>> [...]
>>   7) There is legacy code out there that uses e.g. SCM_SETCDR to set
>>      smob fields.  (This is terrible, but it exists:
>>      https://github.com/search?q=SCM_SETCDR+smob&ref=cmdform&type=Code
>>      for an example.)

(This SMOB case is egregious because the smob is being accessed with
pair macros -- using macros is fine of course.)

> While function declarations are markable as being internal/external in
> published headers (SCM_INTERNAL vs SCM_API), macros are not.
> IWBN to solve this problem for macros too.  If it's in a header and a
> user can get it to work, s/he may just use it - some macros are indeed
> usable, so how does one easily know while reading headers (users will
> do that a lot) which are legitimately usable and which are not?

One can guard macros in #ifdef BUILDING_LIBGUILE, and it's possible to
deprecate them as well by #defining them to invoke SCM_DEPRECATED
functions.  So in short, as a user, you would know if we wanted to
deprecate something, and anything that's there is fair game,
technically.

So that's the minimum API stability barrier.  The higher barrier is
appearing in the documentation.

> [P.S. I'm not sure if SCM_SETCDR is still intended to be usable, I
> wouldn't mind deprecating it, and only publishing the function
> versions.  I can imagine it being ubiquitous enough in existing code
> that that's not possible, even if one wanted to.  At any rate that's a
> separate discussion.  Its presence in the foreign object discussion
> just reminded me of macros in headers.]

This might be a good idea.  Of course deprecation churn is still
unpleasant, so it would have to be a case of actively getting in the way
of some other Guile hacking before SCM_SETCDR could be deprecated in
favor of the (inline) function versions.

Cheers,

Andy
-- 
http://wingolog.org/

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Ludovic Courtès]

Doug Evans <xdje42@gmail.com> skribis:

> While function declarations are markable as being internal/external in
> published headers (SCM_INTERNAL vs SCM_API), macros are not.

Internal macros are marked by a naming convention: they are prefixed by
‘SCM_I’.

If this convention is deemed insufficient, we could #ifdef
BUILDING_GUILE like Andy suggests, but I think this is not always
possible.

> [P.S. I'm not sure if SCM_SETCDR is still intended to be usable,

It is public and usable, and I think that removing it doesn’t really buy
us anything.

Ludo’.

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Doug Evans]

On Fri, May 2, 2014 at 4:44 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> Doug Evans <xdje42@gmail.com> skribis:
>
>> While function declarations are markable as being internal/external in
>> published headers (SCM_INTERNAL vs SCM_API), macros are not.
>
> Internal macros are marked by a naming convention: they are prefixed by
> ‘SCM_I’.

Hi.  Sorry, catching up on mail.

So this means that struct.h:SCM_STRUCT_* are ok to use by apps, right?

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Ludovic Courtès]

Doug Evans <xdje42@gmail.com> skribis:

> On Fri, May 2, 2014 at 4:44 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Doug Evans <xdje42@gmail.com> skribis:
>>
>>> While function declarations are markable as being internal/external in
>>> published headers (SCM_INTERNAL vs SCM_API), macros are not.
>>
>> Internal macros are marked by a naming convention: they are prefixed by
>> ‘SCM_I’.
>
> Hi.  Sorry, catching up on mail.
>
> So this means that struct.h:SCM_STRUCT_* are ok to use by apps, right?

You got me.  ;-)

These ones are not documented, and some of them are clearly too
low-level and expose too many implementation details (flags, indexes,
etc.)

‘SCM_STRUCTP’, ‘SCM_STRUCT_SLOT_REF’, and a few others may be OK, but
there are equivalent public functions anyway, so it’s better to use
them.

I’m not sure what to do for this particular header.

Ludo’.

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Doug Evans]

On Fri, May 2, 2014 at 4:19 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Doug Evans <xdje42@gmail.com> skribis:
>
>> On Fri, May 2, 2014 at 4:44 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>>> Doug Evans <xdje42@gmail.com> skribis:
>>>
>>>> While function declarations are markable as being internal/external in
>>>> published headers (SCM_INTERNAL vs SCM_API), macros are not.
>>>
>>> Internal macros are marked by a naming convention: they are prefixed by
>>> ‘SCM_I’.
>>
>> Hi.  Sorry, catching up on mail.
>>
>> So this means that struct.h:SCM_STRUCT_* are ok to use by apps, right?
>
> You got me.  ;-)
>
> These ones are not documented, and some of them are clearly too
> low-level and expose too many implementation details (flags, indexes,
> etc.)
>
> ‘SCM_STRUCTP’, ‘SCM_STRUCT_SLOT_REF’, and a few others may be OK, but
> there are equivalent public functions anyway, so it’s better to use
> them.

Thing is, the public functions (scm_struct_ref/set_x) are not
equivalent (to SCM_STRUCT_SLOT_*).
Plus the public "slot accessing" functions use the SCM_STRUCT_DATA
interface. :-)
SCM_STRUCT_SLOT_* isn't used at all in struct.c.

$ grep SCM_STRUCT_SLOT struct.c | wc
0 0 0

>
> I’m not sure what to do for this particular header.
>
> Ludo’.

Re: Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Ludovic Courtès]

Doug Evans <xdje42@gmail.com> skribis:

> On Fri, May 2, 2014 at 4:19 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Doug Evans <xdje42@gmail.com> skribis:
>>
>>> On Fri, May 2, 2014 at 4:44 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>>>> Doug Evans <xdje42@gmail.com> skribis:
>>>>
>>>>> While function declarations are markable as being internal/external in
>>>>> published headers (SCM_INTERNAL vs SCM_API), macros are not.
>>>>
>>>> Internal macros are marked by a naming convention: they are prefixed by
>>>> ‘SCM_I’.
>>>
>>> Hi.  Sorry, catching up on mail.
>>>
>>> So this means that struct.h:SCM_STRUCT_* are ok to use by apps, right?
>>
>> You got me.  ;-)
>>
>> These ones are not documented, and some of them are clearly too
>> low-level and expose too many implementation details (flags, indexes,
>> etc.)
>>
>> ‘SCM_STRUCTP’, ‘SCM_STRUCT_SLOT_REF’, and a few others may be OK, but
>> there are equivalent public functions anyway, so it’s better to use
>> them.
>
> Thing is, the public functions (scm_struct_ref/set_x) are not
> equivalent (to SCM_STRUCT_SLOT_*).
> Plus the public "slot accessing" functions use the SCM_STRUCT_DATA
> interface. :-)
> SCM_STRUCT_SLOT_* isn't used at all in struct.c.
>
> $ grep SCM_STRUCT_SLOT struct.c | wc
> 0 0 0

Right.  Well, I don’t know what the intent was, and C-x v g tells me we
should ask Andy.  Andy?  :-)

Interestingly, commit b6cf4d02, which added this, also has this bit:

    Remove foreign object implementation.
    
    * libguile/goops.h:
    * libguile/goops.c (scm_make_foreign_object, scm_make_class)
      (scm_add_slot, scm_wrap_object, scm_wrap_component): Remove, these
      were undocumented and unworking.

Ludo’.