Is ALTREP "non-API"?

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]]

        [[alternative HTML version deleted]]