Hi Yutani, The headers have been updated by Luke Tierney: ALTREP is an *experimental* API, in that it is an official API that is legal for packages to use, but may it change with short notice as the framework is further developed.
Hope that helps, ~G On Mon, Apr 22, 2024 at 4:46 AM Hiroaki Yutani <yutani....@gmail.com> wrote: > 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 <gabembec...@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....@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 <hcortin...@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-boun...@r-project.org> On Behalf Of Hiroaki >>> Yutani >>> > Sent: Sunday, April 21, 2024 8:48 PM >>> > To: r-devel <r-devel@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@r-project.org mailing list >>> > https://stat.ethz.ch/mailman/listinfo/r-devel >>> > >>> > >>> >>> [[alternative HTML version deleted]] >>> >>> ______________________________________________ >>> R-devel@r-project.org mailing list >>> https://stat.ethz.ch/mailman/listinfo/r-devel >>> >> [[alternative HTML version deleted]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
