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 at 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 at 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 at r-project.org> On Behalf Of Hiroaki > Yutani > > Sent: Sunday, April 21, 2024 8:48 PM > > To: r-devel <r-devel at 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 at r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/r-devel > > > > > > [[alternative HTML version deleted]] > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel >[[alternative HTML version deleted]]
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 at 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 at
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 at 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 at r-project.org> On Behalf
Of Hiroaki
>> Yutani
>> > Sent: Sunday, April 21, 2024 8:48 PM
>> > To: r-devel <r-devel at 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 at r-project.org mailing list
>> > https://stat.ethz.ch/mailman/listinfo/r-devel
>> >
>> >
>>
>> [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>
[[alternative HTML version deleted]]
> On Apr 22, 2024, at 7:37 PM, Gabriel Becker <gabembecker at gmail.com> wrote: > > 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). >That is not true at all - the presence of header does not constitute declaration of something as the R API. There are cases where internal functions are in the headers for historical or other reasons since the headers are used both for the internal implementation and packages. That's why this is in R-exts under "The R API: entry points for C code":> There are a large number of entry points in the R executable/DLL that can be called from C code (and some that can be called from Fortran code). Only those documented here are stable enough that they will only be changed with considerable notice.And that's why CRAN does not allow unstable ones = those not documented in R-exts as part of the API. Therefore Hiroaki's question is a very good one. ALTREP is declared as experimental and is not part of the API, but the development and stability of the API in some sense should get better as more packages are using it. Therefore it is currently allowed on CRAN in the hope that it will transition to stable at some point, but package authors using it must be willing to adapt to changes to the API as necessary. Cheers, Simon> 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 at 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 at 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 at r-project.org> On Behalf Of Hiroaki >> Yutani >>> Sent: Sunday, April 21, 2024 8:48 PM >>> To: r-devel <r-devel at 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 at r-project.org mailing list >>> https://stat.ethz.ch/mailman/listinfo/r-devel >>> >>> >> >> [[alternative HTML version deleted]] >> >> ______________________________________________ >> R-devel at r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel >> > > [[alternative HTML version deleted]] > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel >