Re: [Rd] Is ALTREP "non-API"?
> On Apr 25, 2024, at 12:55 AM, Hadley Wickham wrote: > > > > >>> 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": > >>> > >>> If I understand your point correctly, does this mean that > >> Rf_allocVector() is not part of the "official" R API? It does not appear to > >> be documented in the "The R API: entry points for C code" section. > >>> > >> > >> It does, obviously: > >> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 > > > > > > I'm just trying to understand the precise definition of the official API > > here. So it's any function mentioned in R-exts, regardless of which section > > it appears in? > > > > Does this sentence imply that all functions starting with alloc* are part > > of the official API? > > > > Again, I can only quote the R-exts (few lines below the previous "The R API" > quote): > > > We can classify the entry points as > API > 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. > > > It says "in this manual" - I don't see anywhere restriction on a particular > section of the manual, so I really don't see why you would think that > allocation is not part on the API. > > Because you mentioned that section explicitly earlier in the thread. This > obviously seems clear to you, but it's not at all clear to me and I suspect > many of the wider community. It's frustrating because we are trying our best > to do what y'all want us to do, but it feels like we keep getting the rug > pulled out from under us with very little notice, and then have to spend a > large amount of time figuring out workarounds. That is at least feasible for > my team since we have multiple talented folks who are paid full-time to work > on R, but it's a huge struggle for most people who are generally maintaining > packages in their spare time. > I must be missing something here since I have no idea what you are talking about. The whole point if a stable API is that no rugs are pulled, so in fact it's exactly the opposite of what you claim - the notice is at least a year due to the release cycle, typically more. Unlike many other languages and ecosystems, R public API does not change very often - and R-core is thinking hard about making breaking changes if at all. In fact, I hear more complaints that the API does NOT change and we are too conservative, precisely because we want to avoid unnecessary breakage. I will not further comment here - all I did was to point out the relevant text from R-exts which is the canonical source of information. If you have issues, find some parts unclear and want to improve the documentation, I would like to invite you to contribute constructively, propose changes, submit patches. The R-exts document has been around for decades, so it seem implausible that all of sudden it is being misunderstood the way you portrayed it, but it is certainly a good idea to improve documentation so contributions are welcome. Cheers, Simon __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
A few more thoughts based on a simple question: how do you determine the length of a vector? Rf_length() is used in example code in R-exts, but I don't think it's formally documented anywhere (although it's possible I missed it). Is using in an example sufficient to consider a function to be part of the public API? If so, SET_TYPEOF() is used in a number of examples, and hence used by CRAN packages, but is no longer considered part of the public API. Rf_xlength() doesn't appear to be mentioned anywhere in R-exts. Does this imply that long vectors are not part of the exported API? Or is there some other way we should be determining the length of such vectors? Are the macro variants LENGTH and XLENGTH part of the exported API? Are we supposed to use them or avoid them? Relatedly, I presume that LOGICAL() is the way we're supposed to extract logical values from a vector, but it isn't documented in R-exts, suggesting that it's not part of the public API? --- It's also worth pointing out where R-exts does well, with the documentation of utility functions ( https://cran.r-project.org/doc/manuals/R-exts.html#Utility-functions). I think this is what most people would consider documentation to imply, i.e. a list of input arguments/types, the output type, and basic notes on their operation. --- Finally, it's worth noting that there's some lingering ill feelings over how the connections API was treated. It was documented in R-exts only to be later removed, including expunging mentions of it in the news. That's obviously water under the bridge, but I do believe that there is the potential for the R core team to build goodwill with the community if they are willing to engage a bit more with the users of their APIs. Hadley [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
> And in general, I'd urge R Core to make an explicit list of functions that you consider to be part of the exported API While I believe R Core is in the process of such clarification, I'd also vote for this. Now that WRE has "experimental" category, and if we take the current definition of "documented in the manual" literally, an "experimental" entry point cannot be documented because the entry point would promote to an "API" for the obvious reason. It would sound funny that you cannot write precautionary statements on experimental entry points just because of the very definition of "experimental". So, I agree R should have the explicit list. I'd add that R should also define a process on how to stabilize an "experimental" or "public" entry point into an "API". For example, Rust language has such a process [1]. After a feature is introduced as unstable, a "tracking issue" is filed and the related problems are reported or linked to it. Users can know what are the remaining problems before getting stabilized, and, if they have strong will, they can contribute to resolving such blockers. Similarly, if we can track the unresolved problems of each non-API, we might be able to help the R core team more smoothly. Best, Yutani [1]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html 2024年4月24日(水) 21:55 Hadley Wickham : > > > > > > > > >>> 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": > > >>> > > >>> If I understand your point correctly, does this mean that > > >> Rf_allocVector() is not part of the "official" R API? It does not > > appear to > > >> be documented in the "The R API: entry points for C code" section. > > >>> > > >> > > >> It does, obviously: > > >> > https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 > > > > > > > > > I'm just trying to understand the precise definition of the official > API > > > here. So it's any function mentioned in R-exts, regardless of which > > section > > > it appears in? > > > > > > Does this sentence imply that all functions starting with alloc* are > part > > > of the official API? > > > > > > > Again, I can only quote the R-exts (few lines below the previous "The R > > API" quote): > > > > > > We can classify the entry points as > > API > > 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. > > > > > > It says "in this manual" - I don't see anywhere restriction on a > > particular section of the manual, so I really don't see why you would > think > > that allocation is not part on the API. > > > > Because you mentioned that section explicitly earlier in the thread. This > obviously seems clear to you, but it's not at all clear to me and I suspect > many of the wider community. It's frustrating because we are trying > our best to do what y'all want us to do, but it feels like we keep getting > the rug pulled out from under us with very little notice, and then have to > spend a large amount of time figuring out workarounds. That is at least > feasible for my team since we have multiple talented folks who are paid > full-time to work on R, but it's a huge struggle for most people who are > generally maintaining packages in their spare time. > > For the purposes of this discussion could you please "documented in the > manual" means? For example, this line mentions allocXxx functions: "There > are quite a few allocXxx functions defined in Rinternals.h—you may want to > explore them.". Does that imply that they are documented and free to use? > > And in general, I'd urge R Core to make an explicit list of functions that > you consider to be part of the exported API, and then grandfather in > packages that used those functions prior to learning that we weren't > supposed to. > > Hadley > > > -- > http://hadley.nz > > [[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
Re: [Rd] Is ALTREP "non-API"?
> > > > >>> 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": > >>> > >>> If I understand your point correctly, does this mean that > >> Rf_allocVector() is not part of the "official" R API? It does not > appear to > >> be documented in the "The R API: entry points for C code" section. > >>> > >> > >> It does, obviously: > >> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 > > > > > > I'm just trying to understand the precise definition of the official API > > here. So it's any function mentioned in R-exts, regardless of which > section > > it appears in? > > > > Does this sentence imply that all functions starting with alloc* are part > > of the official API? > > > > Again, I can only quote the R-exts (few lines below the previous "The R > API" quote): > > > We can classify the entry points as > API > 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. > > > It says "in this manual" - I don't see anywhere restriction on a > particular section of the manual, so I really don't see why you would think > that allocation is not part on the API. > Because you mentioned that section explicitly earlier in the thread. This obviously seems clear to you, but it's not at all clear to me and I suspect many of the wider community. It's frustrating because we are trying our best to do what y'all want us to do, but it feels like we keep getting the rug pulled out from under us with very little notice, and then have to spend a large amount of time figuring out workarounds. That is at least feasible for my team since we have multiple talented folks who are paid full-time to work on R, but it's a huge struggle for most people who are generally maintaining packages in their spare time. For the purposes of this discussion could you please "documented in the manual" means? For example, this line mentions allocXxx functions: "There are quite a few allocXxx functions defined in Rinternals.h—you may want to explore them.". Does that imply that they are documented and free to use? And in general, I'd urge R Core to make an explicit list of functions that you consider to be part of the exported API, and then grandfather in packages that used those functions prior to learning that we weren't supposed to. Hadley -- http://hadley.nz [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
> On Apr 24, 2024, at 12:52 AM, Hadley Wickham wrote: > >> >> >> 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": >>> >>> If I understand your point correctly, does this mean that >> Rf_allocVector() is not part of the "official" R API? It does not appear to >> be documented in the "The R API: entry points for C code" section. >>> >> >> It does, obviously: >> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 > > > I'm just trying to understand the precise definition of the official API > here. So it's any function mentioned in R-exts, regardless of which section > it appears in? > > Does this sentence imply that all functions starting with alloc* are part > of the official API? > Again, I can only quote the R-exts (few lines below the previous "The R API" quote): We can classify the entry points as API 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. It says "in this manual" - I don't see anywhere restriction on a particular section of the manual, so I really don't see why you would think that allocation is not part on the API. Cheers, Simon >> For many purposes it is sufficient to allocate R objects and manipulate > those. There are quite a >> few allocXxx functions defined in Rinternals.h—you may want to explore > them. > > Generally, things in a file with "internal" in its name are internal. > > Hadley > > -- > http://hadley.nz > > [[alternative HTML version deleted]] > > __ > R-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
> > > > > > 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": > > > > If I understand your point correctly, does this mean that > Rf_allocVector() is not part of the "official" R API? It does not appear to > be documented in the "The R API: entry points for C code" section. > > > > It does, obviously: > https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 I'm just trying to understand the precise definition of the official API here. So it's any function mentioned in R-exts, regardless of which section it appears in? Does this sentence imply that all functions starting with alloc* are part of the official API? > For many purposes it is sufficient to allocate R objects and manipulate those. There are quite a > few allocXxx functions defined in Rinternals.h—you may want to explore them. Generally, things in a file with "internal" in its name are internal. Hadley -- http://hadley.nz [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
I just saw the recent commits about the "experimental" entry points. So, my original question about the current status of ALTREP is now resolved. I'm glad that ALTREP is confirmed usable on CRAN (with care). Thank you for all your help! I think other "non-API"s still need clarification. For example, this one I picked in my previous email. > 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? But, in my understanding, R is now in the process of clearing such ambiguities. So, I can just wait. Lastly, I want the R core to consider marking ALTREP as stable, or the "API". I didn't actively follow the development of ALTREP, but I think the ALTREP entry points have been there for half a decade without any major breaking changes. So, in my opinion, it's safe to declare it's stable. Best, Yutani 2024年4月23日(火) 7:14 Simon Urbanek : > > > > On Apr 22, 2024, at 7:37 PM, Gabriel Becker > 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 > 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 : > >> > >>> 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 > &
Re: [Rd] Is ALTREP "non-API"?
> On Apr 23, 2024, at 10:29 AM, Hadley Wickham wrote: > > > > On Mon, Apr 22, 2024 at 5:14 PM Simon Urbanek > wrote: > > > > On Apr 22, 2024, at 7:37 PM, Gabriel Becker 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": > > If I understand your point correctly, does this mean that Rf_allocVector() is > not part of the "official" R API? It does not appear to be documented in the > "The R API: entry points for C code" section. > It does, obviously: https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1 Cheers, Simon __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
On Mon, Apr 22, 2024 at 5:14 PM Simon Urbanek wrote: > > > > On Apr 22, 2024, at 7:37 PM, Gabriel Becker > 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": > If I understand your point correctly, does this mean that Rf_allocVector() is not part of the "official" R API? It does not appear to be documented in the "The R API: entry points for C code" section. Hadley -- http://hadley.nz [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
> On Apr 22, 2024, at 7:37 PM, Gabriel Becker 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 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 : >> >>> 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 On Behalf Of Hiroaki >> Yutani >>> Sent: Sunday, April 21, 2024 8:48 PM >>> To: r-devel >>> 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 > __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Is ALTREP "non-API"?
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 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 : > >> 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 >> 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 : >>> >>> > 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 >>>
Re: [Rd] 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 : > 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 > 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 : >> >> > 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 On Behalf Of Hiroaki >> Yutani >> > Sent: Sunday, April 21, 2024 8:48 PM >> > To: r-devel >> > 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 p
Re: [Rd] Is ALTREP "non-API"?
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 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 : > > > 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 On Behalf Of Hiroaki > Yutani > > Sent: Sunday, April 21, 2024 8:48 PM > > To: r-devel > > 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
Re: [Rd] Is ALTREP "non-API"?
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 : > 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 On Behalf Of Hiroaki Yutani > Sent: Sunday, April 21, 2024 8:48 PM > To: r-devel > 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
Re: [Rd] Is ALTREP "non-API"?
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 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 On Behalf Of Hiroaki Yutani Sent: Sunday, April 21, 2024 8:48 PM To: r-devel 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 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
[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