[Rd] Is ALTREP "non-API"?

[Hiroaki Yutani]

Thanks for your convincing comment, but it seems the R core team has a
different opinion...
A few hours ago, src/include/R_ext/Altrep.h got this comment:

    /*
       Not part of the API, subject to change at any time.
    */

commit:
https://github.com/r-devel/r-svn/commit/2059bffde642f8426d1f39ab5dd995d19a575d4d

While I'm glad to see their attempt to make it clear, I'm confused. That
commit marks many other files as "not API," but I think it's a bit
inconsistent with what Writing R Extension says.

For example, src/include/R_ext/Parse.h got a comment "So not API," but the
entry point R_ParseVector is explained in Writing R Extension[1]. So, I
believe it's clearly an "API" both in the sense of WRE's dialect and in an
ordinary sense. Which should I believe? WRE? The source code?

It might be just a coincidence, but I'm sorry if my question drove the R
core team to such a too-quick clarification. I just wanted to discuss how
to fix the current inconsistencies.

I think the R core needs a proper definition of "API" first. In my opinion,
it makes little sense to call it "non-API" just to show the possibility of
future breaking changes. Whether you call it API or non-API, clever users
will still accept the breaking changes on it if it's reasonable. For
example, how about "experimental API" or "unstable API"? They sound better
to me.

Best,
Yutani

[1]:
https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Parsing-R-code-from-C


2024年4月22日(月) 16:37 Gabriel Becker <gabembecker using gmail.com>:

> Hi Yutani,
>
> ALTREP is part of the official R api, as illustrated by the presence of
> src/include/R_ext/Altrep.h. Everything declared in the header files in that
> directory is official API AFAIK (and I believe that is more definitive than
> the manuals).
>
> The documentation of ALTREP has lagged behind its implementation
> unfortunately, which may partially my fault for not submitting doc
> patches for it against the manuals. Sorry for my contribution to that, I'll
> see if I can loop back around to contributing documentation for ALTREP.
>
> Best,
> ~G
>
> On Sun, Apr 21, 2024 at 6:36 PM Hiroaki Yutani <yutani.ini using gmail.com>
> wrote:
>
>> Thanks, Hernando,
>>
>> Sorry, "API" is a bit confusing term in this context, but what I want to
>> discuss is the "API" that Writing R Extension defines as quoted in my
>> previous email. It's probably different from an ordinary sense when we
>> casually say "R C API".
>>
>> You might wonder why I care about such a difference. This is because
>> calling a "non-API" is considered a violation of CRAN repository policy,
>> which means CRAN will kick out the R package. I know many CRAN packages
>> use
>> ALTREP, but just being accepted by CRAN at the moment doesn't mean CRAN
>> will keep accepting it. So, I want to clarify the current status of
>> ALTREP.
>>
>> Best,
>> Yutani
>>
>> 2024年4月22日(月) 10:17 <hcortina71 using gmail.com>:
>>
>> > Hello, I don't believe it is illegal, as ALTREP "implements an
>> abstraction
>> > underneath the C API". And is "compatible with all code which uses the
>> > API".
>> >
>> > Please see slide deck by Gabriel Becker,  with L Tierney, M Lawrence
>> and T
>> > Kalibera.
>> >
>> >
>> >
>> https://bioconductor.org/help/course-materials/2020/BiocDevelForum/16-ALTREP
>> > .pdf
>> > <
>> https://bioconductor.org/help/course-materials/2020/BiocDevelForum/16-ALTREP.pdf
>> >
>> >
>> > ALTREP framework implements an abstraction underneath traditional R C
>> API
>> > - Generalizes whats underneath the API
>> > - Without changing how data are accessed
>> > - Compatible with all C code which uses the API
>> > - Compatible with R internals
>> >
>> >
>> > I hope this helps,
>> > Hernando
>> >
>> >
>> > -----Original Message-----
>> > From: R-devel <r-devel-bounces using r-project.org> On Behalf Of Hiroaki
>> Yutani
>> > Sent: Sunday, April 21, 2024 8:48 PM
>> > To: r-devel <r-devel using r-project.org>
>> > Subject: [Rd] Is ALTREP "non-API"?
>> >
>> > Writing R Extension[1] defines "API" as:
>> >
>> >     Entry points which are documented in this manual and declared in an
>> > installed header file. These can be used in distributed packages and
>> will
>> > only be changed after deprecation.
>> >
>> > But, the document (WRE) doesn't have even a single mention of ALTREP,
>> the
>> > term "ALTREP" itself or any entry points related to ALTREP. Does this
>> mean,
>> > despite the widespread use of it on R packages including CRAN ones,
>> ALTREP
>> > is not the API and accordingly using it in distributed packages is
>> > considered illegal?
>> >
>> > Best,
>> > Yutani
>> >
>> > [1]:
>> > https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-R-API
>> >
>> >         [[alternative HTML version deleted]]
>> >
>> > ______________________________________________
>> > R-devel using r-project.org mailing list
>> > https://stat.ethz.ch/mailman/listinfo/r-devel
>> >
>> >
>>
>>         [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> R-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>

	[[alternative HTML version deleted]]