[Rd] Is ALTREP "non-API"?

[Gabriel Becker]

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.ini using 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 <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]]