[Rcpp-commits] r2177 - papers/rjournal
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Sep 25 20:03:54 CEST 2010
Author: romain
Date: 2010-09-25 20:03:54 +0200 (Sat, 25 Sep 2010)
New Revision: 2177
Modified:
papers/rjournal/EddelbuettelFrancois.tex
Log:
inline discussion
Modified: papers/rjournal/EddelbuettelFrancois.tex
===================================================================
--- papers/rjournal/EddelbuettelFrancois.tex 2010-09-25 17:54:21 UTC (rev 2176)
+++ papers/rjournal/EddelbuettelFrancois.tex 2010-09-25 18:03:54 UTC (rev 2177)
@@ -30,25 +30,12 @@
a short review of other approaches and give some historical
background on the development of \pkg{Rcpp}.
-% [romain] : removing this paragraph from the introduction.
-% The article is about today's Rcpp, the only place where the classic
-% api should be is in the hist(e|o)rical section.
-% [dirk] : the classix API will be supported, is the past of Rcpp and may
-% as well be mentioned. We have nothing to hide
-% please see the next paragraph where I now talk about classic
-% but also note deprecated and link to the recommended new API
-% [romain] : alright
-% [dirk] : great, will remove discussion in next revision
-
-%The current version of
The \pkg{Rcpp} package combines two distinct
APIs. The first---which we call `classic \pkg{Rcpp} API'---exists since
the first version of \pkg{Rcpp}. While still contained in the package to
ensure compatibility, its use is otherwise deprecated. All new development should
use the newer and richer second API. It is enclosed in the \code{Rcpp} C++
namespace, and corresponds to the newer redesigned codebase.
-% which we started to develop more recently. -- [dirk] start no longer recent
-%
This article highlights some of the key design and implementation choices of
the new API: lightweight encapsulation of R objects in C++ classes, automatic
garbage collection strategy, code inlining, data interchange between R and
@@ -83,21 +70,6 @@
seven vignettes included with the package. This new API is our current focus,
and we intend to both extend and support it in future development of the
package.
-%% TODO Should we talk about RcppExamples and/or RcppArmadillo here?
-% [romain] I don't like the word "New" anymore. Was certainly appropriate in
-% february, but no longer is now.
-% Furthermore, I don't think we did extend the codebase per se,
-% we rather started more or less from scratch. I'd like something
-% like "Rcpp was redesigned" ...
-% [dirk] 'new' should stay as we have the term consistently to contrast
-% with 'classic'. We support both APIs, we need labels for both
-% 'new' and 'classic' work
-% OTOH "Rcpp was redesigned" could work instead of 'extend'
-% I gave it a spin above (and sorry about the reindent)
-% [ minutes later ]
-% ok, one 'new' is gone above as the corresponding section title is gone
-% [romain] fine
-% [dirk] good, will clean out discussion here too
\subsection{Comparison}
@@ -129,24 +101,12 @@
Another slightly different angle is offered by
\cite{templelang09:rgcctranslationunit} who uses compiler output for
references on the code in order to add bindings and wrappers.
-%
-% The \pkg{cxxPack} package \citep{cran:cxxPack} builds on top of
-% \pkg{Rcpp} and adds a small collection of diverse functions.
-% [romain] So what ? Is this the mention you want to remove ? Go right ahead !
-% [dirk] Done!!
%DE: Removed per editor
%A critical comparison of these packages that addresses relevant aspects such
%API features, performance, usability and documentation would be a welcome
%addition to the literature, but is beyond the scope of this article.
-% [romain] FIXME: this section is now irrelevant. it needs to go.
-% [dirk] the first two paragraphs are generic and still true for the new
-% API (irrespective of the fact that it does more too)
-% Maybe we make it a 'subsection' and part of the 'Introduction'
-% section?
-
-%\section{Classic Rcpp API}
\subsection{Rcpp Use Cases} % or some such
\label{sec:classic_rcpp}
@@ -177,9 +137,8 @@
% to combine them ... go for it.
% [dirk] : also, we could call this 'vertical' mode and use 'horizontal'
% below but I can't recall if you hate or love that language
+% [romain] : I just don't speak it.
-
-
\section{The \pkg{Rcpp} API}
\label{sec:new_rcpp}
@@ -211,9 +170,9 @@
return xab;
}
\end{example}
-% [dirk] shall we change the name from convolve3cpp now that we have no 1 or 2?
+% [dirk] : shall we change the name from convolve3cpp now that we have no 1 or 2?
+% [romain] : it is consistent with the examples in the package
-
We can highlight several aspects. First, only a single header file
\code{Rcpp.h} is needed to use the \pkg{Rcpp} API. Second, given two
\code{SEXP} types, a third is returned. Third, both inputs are
@@ -222,13 +181,6 @@
usefulness of these classes can be seen when we query the vectors directly
for their size---using the \code{size()} member function---in order to
reserve a new result type of appropriate length,
-% whereas use based on C arrays
-% would have required additional parameters for the length of vectors $a$ and
-% $b$, leaving open the possibility of mismatches between the actual length and
-% the length reported by the programmer.
-% [romain] : hmmm. There is no need for extra parameters if you use .Call
-% with the R API. I don't think the point is valid.
-% [dirk] Nice catch ctach
and with the use of the
\verb|operator[]| to extract and set individual elements of the vector.
Fifth, the computation itself is
@@ -237,9 +189,7 @@
is also automatic from the \code{NumericVector} to the \code{SEXP} type.
We argue that this usage is much easier to read, write and debug than the
-C macro-based approach supported by R itself. %Possible performance issues and
-%other potential limitations will be discussed throughout the article and
-%reviewed at the end.
+C macro-based approach supported by R itself.
% [dirk] TODO maybe another sentence to tie into the next segment
@@ -321,8 +271,7 @@
Memory is allocated by \code{allocVector}; we must also supply it with
the type of data (\code{REALSXP}) and the number of elements. Once
allocated, the \code{ab} object must be protected from garbage
-collection.%\footnote{Since the garbage collection can be triggered at any time, not
-%protecting an object means its memory might be reclaimed too soon.}.
+collection.
Lastly, the \code{REAL} macro returns a pointer to the
beginning of the actual array; its indexing does not resemble either R or
C++.
@@ -343,18 +292,6 @@
the first and second elements of the vector as \code{NumericVector} overloads
the \code{operator[]}.
-% With the most recent compilers (e.g. GNU g++ >= 4.4) which already implement
-% parts of the next C++ standard (C++0x) currently being drafted, the preceding
-% code may even be reduced to this:
-%
-% \begin{example}
-% Rcpp::NumericVector ab = \{123.45, 67.89\};
-% \end{example}
-% [romain] I'm trading this for the use of create, as this always works
-% so that we don't confuse readers because if you have gcc 4.4
-% you don't get this automatically, you have to enable it, etc ...
-% [dirk] Nicely done!
-
The snippet can also be written more concisely using the \code{create}
static member function of the \code{NumericVector} class:
@@ -366,7 +303,8 @@
It should be noted that although the copy constructor of the
\code{NumericVector} class is used, it does not imply copies of the
underlying array, only the \code{SEXP} is copied.
-% [dirk] Huh? But so there is a copy?
+% [dirk] : Huh? But so there is a copy?
+% [romain] : yes. a copy of the pointer.
\subsection{Character vectors}
@@ -432,7 +370,7 @@
the type \code{T} is wrappable;
\item any type that implements implicit conversion to \code{SEXP} through the
\code{operator SEXP()};
-\item any type for which the \code{wrap} template is % partially or [romain] partially is not true anymore
+\item any type for which the \code{wrap} template is
fully specialized.
\end{itemize}
@@ -597,7 +535,9 @@
\texttt{using namespace Rcpp;} in the code}
\label{fig:rnormCode}
\end{table*}
-% [dirk] Do we now need to mention sugar as a third case for rnorm()? Footnote ?
+% [dirk] : Do we now need to mention sugar as a third case for rnorm()? Footnote ?
+% [romain] : I'd love to, but there is no much space left. we can do sugar in the
+% next paper
The next example shows how to use \pkg{Rcpp} to emulate the R code
\code{rnorm(10L, sd=100.0)}.
@@ -614,8 +554,6 @@
that is easier to read, write and maintain. More examples are available as
part of the documentation included in the \pkg{Rcpp} package, as well as
among its over seven hundred and seventy unit tests.
-% TODO: bump this up to the current test count
-% [dirk] done, good catch
\section{Using code `inline'}
\label{sec:inline}
@@ -677,14 +615,6 @@
[1] 1 4 10 16 17 12
\end{example}
-% The main difference to the previous solution is that the input parameters are
-% directly passed to types \code{Rcpp::NumericVector}, and that the return
-% vector is automatically converted to a \code{SEXP} type through implicit
-% conversion.
-% Also in this version, the vector \code{xab} is not
-% initialized because the constructor already performs initialization
-% to match the behavior of the R function \code{numeric}.
-
\section{Using STL algorithms}
% [romain] hmmmm. we do now have sapply and lapply. I think we should mention
@@ -909,10 +839,12 @@
\end{center}
\end{table}
-% [dirk] so what do we want to show here? I like our new table, I
-% particularly like the difference between R API "naive" (which does
-% pretty badly !!) and the highly optimised one. We do look good.
-% So we toss Classic, and I guess we also toss Sugar for now?
+% [dirk] so what do we want to show here? I like our new table, I
+% particularly like the difference between R API "naive" (which does
+% pretty badly !!) and the highly optimised one. We do look good.
+% So we toss Classic, and I guess we also toss Sugar for now?
+% [romain] things have changed now. we definitely want the nona version of sugar
+% I'm not convinced about showing the naive version of R API
The first implementation, using the traditional R API, unsurprisingly
appears to be the most efficient. It takes advantage of pointer
@@ -939,8 +871,9 @@
the code using the new API can essentially as fast as the R API base case
while being easier to write.
-% [dirk] TODO Should we talk about sugar?
+% [dirk] TODO Should we talk about sugar?
% [dirk] TODO Should we talk about modules?
+% [romain] let's do another paper, or start working on the book
\section{Summary}
More information about the Rcpp-commits
mailing list