Re: interface reductions

[Mikael Djurfeldt <mdj at mdj dot nada dot kth dot se>]

Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

> On 24 May 2000, Mikael Djurfeldt wrote:
> 
> > All scm_tc16_* codes should be declared in *.h files.  A lot of the
> > scm_tc16_ codes need to be accessible across compilation units.  It is
> > better to be consistent than to have to make things public when
> > needed.
> > 
> > Similarly, as many Guile data types as possible should have type
> > predicates declared in header files so that applications and Guile C
> > modules can use them.

[...]

> Hmmm... I would have understood your arguments if you would have argued
> the other way around, like 'We should provide predicates in header files, 
> and these predicates need the scm_tc16_* codes'.  As you put it, it seems
> that it is OK for external applications to explicitly use the scm_tc16_*
> codes.  This, however, is not a good idea, IMO, since the fact that a type
> is a smob should be hidden.  Otherwise, once such a type is implemented in
> a different way, using goops for example, all external code has to be
> changed.
> 
> However, it's probably OK to keep the predicates, and as a consequence,
> the scm_tc16_* codes,

That is exactly what I meant.  I mention the application in relation
to the predicates.  The first paragraph is related to Guile internals.

> but I would strongly recommend to deprecate the explicit use of the
> scm_tc16_* codes by user code.

Yes, that seems good.

> > Furthermore, we need to keep in mind that the scm_ interface has two
> > roles: 1. implementing Guile, 2. being an interface for applications
> > and Guile C modules.  On these grounds, the following macros should be
> > kept:
> > 
> > > fluids.h:
> > >   SCM_FLUID_NUM
> > >   SCM_FAST_FLUID_REF
> > >   SCM_FAST_FLUID_SET_X
> 
> These macros rely heavily on the way fluids are implemented, i. e. the
> fact that they are kept in a vector and thus have a numeric index.  While
> I am not against providing an as-fast-as-possible interface, I question
> this if it couples user code closely to an implementation detail.

The primary objective for Guile is to be useful.  While I agree that
we could construct a better API for fluids, we should not remove
functionality until this has been implemented.  It is probably a good
idea to write a warning that these macros might *become* deprecated in
the future, both in comments and in the manual.

I appreciate your cleanups a lot.   It's just that we should avoid
removing useful functionality, and postpone some changes until the
"real" fix is implemented.

> > >   SCM_HOOK_NAME
> 
> This is not actually related to the question of whether this macro
> should be deprecated, but:  Does it make sense to have objects with
> names?  If we think of a name being an essential part of a hook, then it
> is OK to provide functions for accessing it.  But, I don't think that
> hooks should have a name.  Otherwise, you could give names to any kind of
> scheme object, like cells with names :-)

Personally, I agree.  I think this was added because the SCWM people
claimed that it was good for debugging if hooks have names.

We should dig up the motivation from the Guile list archive...

> > > validate.h:
> > >   SCM_VALIDATE_NUMBER_COPY
> > >   SCM_VALIDATE_BIGINT
> > 
> > SCM_VALIDATE_NUMBER_COPY was added April 17...  It was added because
> > it was needed in an application.  It seems reasonable to support
> > validating a numeric argument, don't you think?
> 
> Have you looked at SCM_VALIDATE_NUMBER_COPY?  It converts a numeric
> argument to a double value.  It's nothing that the name tells you
> about.  It does not work with complex values.  The fact that an
> application uses it doesn't make it better.  Maybe that application should
> have provided it's own special purpose macro, but the way
> SCM_VALIDATE_NUMBER_COPY works is broken IMO.  Nothing against a
> SCM_VALIDATE_NUMBER, though, or maybe even a SCM_VALIDATE_REAL_COPY.

Let's rename it to SCM_VALIDATE_REAL_COPY.  I think this is a commonly
needed operation.

> > > keywords.h:
> > >   SCM_KEYWORDSYM
> 
> Again, coupling to the implementation detail that keywords are implemented
> as symbols.

As with fluids, let's keep it until we can provide equivalent
functionality in a better API.

> > > numbers.h:
> > >   SCM_MAXEXP
> > >   SCM_DIGSTOOBIG
> > >   SCM_DIGSPERLONG
> > >   SCM_BIGUP
> > >   SCM_LONGLONGBIGUP
> > >   SCM_BIGDN
> > >   SCM_BIGLO
> > >   SCM_BIGSIGNFLAG
> > >   SCM_BIGSIGN
> > >   SCM_SETNUMDIGS
> > 
> > (I didn't look at the details of the BIGNUM macros.  Since we're going
> >  to replace the bignums with libgmp, most of these will be irrelevant,
> >  but there's no reason why we should remove them now.)
> 
> I'm not suggesting to _remove_ these, but rather to allow developers to
> detect uses of these by enabling SCM_DEBUG_DEPRECATED.  Since bignums are
> to be replaced, we should deprecate these macros ASAP.
> 
> That's, btw, what I actually suggested for all those macros:  Not to
> _remove_ them now, but deprecate them, at least for external
> use.  However, as you see I follow your argument for a number of these
> macros, but there are still a lot for which you did not convince me
> (yet?).

In the general case, we can't deprecate things until there exists some
substitute.  There should always be a valid alternative.  That is,
when we mark something as "deprecated", we should be able to say how
the (currently) real solution looks like.

In the bignums case, however, matters are pretty hopeless, because we
won't feel motivated to supply old, deprecated versions of the bignum
macros when we switch to libgmp.

Mark them if you wish.  Personally, I would save my energy for
implementing the real solution.