Skip to content

C data.table docs and minor rename #4753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattdowle merged 5 commits into from
Apr 14, 2021
Merged

C data.table docs and minor rename #4753

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
750e141
C data.table docs and minor rename
jangorecki Oct 12, 2020
9c0ffc3
news item
jangorecki Oct 12, 2020
42ebb79
typo and wording
jangorecki Oct 12, 2020
518b80e
Merge branch 'master' into cdt5
mattdowle Apr 14, 2021
84cdc4b
moved news item up
mattdowle Apr 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@
nafill(x, fill=as.integer(3.14)) # no warning; the as.<type> conveys intent
```

2. `CsubsetDT` exported C function has been renamed to `DT_subsetDT`. This requires `R_GetCCallable("data.table", "CsubsetDT")` to be updated to `R_GetCCallable("data.table", "DT_subsetDT")`. Additionally there is now a dedicated header file for data.table C exports `include/datatableAPI.h`, [#4643](https://github.com/Rdatatable/data.table/issues/4643), thanks to @eddelbuettel, which makes it easier to _import_ data.table C functions.


# data.table [v1.14.0](https://github.com/Rdatatable/data.table/milestone/23?closed=1) (21 Feb 2021)

## POTENTIALLY BREAKING CHANGES
Expand Down
5 changes: 4 additions & 1 deletion inst/include/datatableAPI.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,14 @@ extern "C" {
/* provided the interface for the function exported in
../src/init.c via R_RegisterCCallable() */

// subsetDT #3751
inline SEXP attribute_hidden DT_subsetDT(SEXP x, SEXP rows, SEXP cols) {
static SEXP(*fun)(SEXP, SEXP, SEXP) =
(SEXP(*)(SEXP,SEXP,SEXP)) R_GetCCallable("data.table", "CsubsetDT");
(SEXP(*)(SEXP,SEXP,SEXP)) R_GetCCallable("data.table", "DT_subsetDT");
return fun(x,rows,cols);
}
// forder #4015
// setalloccol alloccolwrapper setDT #4439

/* permit opt-in to redefine shorter identifiers */
#if defined(DATATABLE_REMAP_API)
Expand Down
17 changes: 12 additions & 5 deletions man/cdt.Rd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,25 @@
\alias{cdatatable}
\title{ data.table exported C routines }
\description{
Note that this interface is going to be changed in next release.
Some of internally used C routines are now exported. This interface should be considered experimental. List of exported C routines and their signatures are provided below in the usage section.
}
\usage{
# SEXP subsetDT(SEXP x, SEXP rows, SEXP cols);
# p_dtCsubsetDT = R_GetCCallable("data.table", "CsubsetDT");
# SEXP DT_subsetDT(SEXP x, SEXP rows, SEXP cols);
# p_DT_subsetDT = R_GetCCallable("data.table", "DT_subsetDT");
}
\details{
For details how to use those see \emph{Writing R Extensions} manual \emph{Linking to native routines in other packages} section.
Details how to use those can be found in \emph{Writing R Extensions} manual \emph{Linking to native routines in other packages} section.
An example use with \code{Rcpp}:
\preformatted{
dt = data.table::as.data.table(iris)
Rcpp::cppFunction("SEXP mysub2(SEXP x, SEXP rows, SEXP cols) { return DT_subsetDT(x,rows,cols); }",
include="#include <datatableAPI.h>",
depends="data.table")
mysub2(dt, 1:4, 1:4)
Comment on lines +15 to +19
Copy link
Copy Markdown
Member Author

@jangorecki jangorecki Oct 12, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This Dirk example is really nice and shows how new header can be nicely used. I would like to provide pure C example as well but cannot get it to work.

dt = data.table::as.data.table(iris)
mysub1 = inline::cfunction(sig=c(x="SEXP", rows="integer", cols="integer"),
  "return DT_subsetDT(x,rows,cols); ",
  includes = "#include <datatableAPI.h>",
  cppargs = paste0("-I",system.file("include", package="data.table")),
  language = "C")

@eddelbuettel any idea how to effectively use new header file for linking from C? if possible just base R, not even inline, for simplicity

Copy link
Copy Markdown
Contributor

@eddelbuettel eddelbuettel Oct 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jangorecki Can you please rephrase that question? What is your are asking? Header files are using during compilation only (and we can all blame R's LinkingTo: for confusion). Are you aiming for an example in R using a header file but no compiler? I can't quite square it ...

Copy link
Copy Markdown
Member Author

@jangorecki jangorecki Oct 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strictly speaking an example of importing DT's functions by importing API header rather than R_GetCCallable("data.table", "DT_subsetDT"). For use from C rather than C++.

Copy link
Copy Markdown
Contributor

@eddelbuettel eddelbuettel Oct 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you asking if I have a package hanging around that uses the new C header? No, as it is still fairly new.

But you could take aim at for example RcppXts which was set up (well over seven and a half years ago !!) to do the same xts and the export header there.

It would be possible (and in fact very valuable) to have a similar examples package for data.table. But right now we have ... one function. Little stretched for an example package.

}
}
\note{
Be aware C routines are likely to have less input validation than their corresponding R interface. For example one should not expect \code{DT[-5L]} will be equal to \code{.Call(CsubsetDT, DT, -5L, seq_along(DT))} because translation of \code{i=-5L} to \code{seq_len(nrow(DT))[-5L]} might be happening on R level. Moreover checks that \code{i} argument is in range of \code{1:nrow(DT)}, missingness, etc. might be happening on R level too.
Be aware C routines are likely to have less input validation than their corresponding R interface. For example one should not expect \code{DT[-5L]} will be equal to \code{.Call(DT_subsetDT, DT, -5L, seq_along(DT))} because translation of \code{i=-5L} to \code{seq_len(nrow(DT))[-5L]} might be happening on R level. Moreover checks that \code{i} argument is in range of \code{1:nrow(DT)}, missingness, etc. might be happening on R level too.
}
\references{
\url{https://cran.r-project.org/doc/manuals/r-release/R-exts.html}
Expand Down
6 changes: 4 additions & 2 deletions src/init.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,8 +245,10 @@ static void setSizes() {
void attribute_visible R_init_datatable(DllInfo *info)
// relies on pkg/src/Makevars to mv data.table.so to datatable.so
{
// C exported routines, see ?cdt for details
R_RegisterCCallable("data.table", "CsubsetDT", (DL_FUNC) &subsetDT);
// C exported routines
// must be also listed in inst/include/datatableAPI.h
// for end user documentation see ?cdt
R_RegisterCCallable("data.table", "DT_subsetDT", (DL_FUNC) &subsetDT);

R_registerRoutines(info, NULL, callMethods, NULL, externalMethods);
R_useDynamicSymbols(info, FALSE);
Expand Down