[Rcpp-commits] r4152 - in pkg/Rcpp: . inst/doc/Rcpp-attributes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Dec 11 18:57:13 CET 2012
Author: jjallaire
Date: 2012-12-11 18:57:13 +0100 (Tue, 11 Dec 2012)
New Revision: 4152
Modified:
pkg/Rcpp/ChangeLog
pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
Log:
update vignette for changes to attributes in 0.10.2
Modified: pkg/Rcpp/ChangeLog
===================================================================
--- pkg/Rcpp/ChangeLog 2012-12-11 15:59:57 UTC (rev 4151)
+++ pkg/Rcpp/ChangeLog 2012-12-11 17:57:13 UTC (rev 4152)
@@ -10,6 +10,8 @@
* src/AttributesTypes.h: consolidate attributes into single file
* src/AttributesUtil.h: consolidate attributes into single file
* inst/NEWS.Rd: additional notes on changes to attributes
+ * inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw: update for changes
+ to attributes in 0.10.2
2012-12-11 Romain Francois <romain at r-enthusiasts.com>
Modified: pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw 2012-12-11 15:59:57 UTC (rev 4151)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw 2012-12-11 17:57:13 UTC (rev 4152)
@@ -84,9 +84,8 @@
functions as callable from \proglang{R} and automatically generating the code
required to invoke them. Attributes are intended to facilitate both interactive use
of \proglang{C++} within \proglang{R} sessions as well as to support \proglang{R}
- package development. Attributes are built on top of \pkg{Rcpp} modules
- and their implementation is based on previous work in the \pkg{inline}
- package \citep{CRAN:inline}.
+ package development. The implementation of attributes is based on previous
+ work in the \pkg{inline} package \citep{CRAN:inline}.
}
@@ -128,8 +127,9 @@
\end{itemize}
Attributes can also be used for package development via the
-\texttt{compileAttributes} function, which generates an \pkg{Rcpp} module for
-all exported functions within a package.
+\texttt{compileAttributes} function, which automatically generates
+\texttt{extern "C"} and \texttt{.Call} wrappers for \proglang{C++}
+functions within pacakges.
\section{Using Attributes}
@@ -254,12 +254,12 @@
Will be exported to R as:
% \begin{verbatim}
-% function (file, colNames = character(0), commentChar = "#", header = TRUE)
+% function (file, colNames = character(), commentChar = "#", header = TRUE)
% \end{verbatim}
\begin{kframe}
\noindent
\ttfamily
-\hlstd{}\hlkwa{function\ }\hlstd{}\hlopt{(}\hlstd{file}\hlopt{,\ }\hlstd{cols\ }\hlopt{=\ }\hlstd{}\hlkwd{character}\hlstd{}\hlopt{(}\hlstd{}\hlnum{0}\hlstd{}\hlopt{),\ }\hlstd{comment\ }\hlopt{=\ }\hlstd{}\hlstr{"\#"}\hlstd{}\hlopt{,\ }\hlstd{header\ }\hlopt{=\ }\hlstd{}\hlkwb{TRUE}\hlstd{}\hlopt{)\ }\hlstd{}\hspace*{\fill}
+\hlstd{}\hlkwa{function\ }\hlstd{}\hlopt{(}\hlstd{file}\hlopt{,\ }\hlstd{cols\ }\hlopt{=\ }\hlstd{}\hlkwd{character}\hlstd{}\hlopt{(),\ }\hlstd{comment\ }\hlopt{=\ }\hlstd{}\hlstr{"\#"}\hlstd{}\hlopt{,\ }\hlstd{header\ }\hlopt{=\ }\hlstd{}\hlkwb{TRUE}\hlstd{}\hlopt{)\ }\hlstd{}\hspace*{\fill}
\mbox{}
\normalfont
\normalsize
@@ -269,6 +269,30 @@
consecutively at the end of the function signature and (unlike R) can't rely
on the values of other arguments.
+Not all \proglang{C++} defualt argument values can be parsed into their
+\proglang{R} equivalents, however the most common cases are supported, including:
+
+\begin{itemize}
+\item
+ String literals delimited by quotes (e.g. \texttt{"foo"})
+\item
+ Decimal numeric values (e.g. \texttt{10} or \texttt{4.5})
+\item
+ Pre-defined constants including \texttt{true}, \texttt{false},
+ \texttt{R\_NilValue}, \texttt{NA\_STRING}, \texttt{NA\_INTEGER},
+ \texttt{NA\_REAL}, and \texttt{NA\_LOGICAL}.
+\item
+ Selected vector types (\texttt{CharacterVector}, \texttt{IntegerVector},
+ and \texttt{NumericVector}) instantiated using the \texttt{::create}
+ static member function.
+\item
+ \texttt{Matrix} types instantiated using the \texttt{rows},
+ \texttt{cols} constructor.
+\end{itemize}
+
+
+\pagebreak
+
\subsection{Signaling Errors}
Within \proglang{R} code the \texttt{stop} function is typically used to signal
@@ -349,9 +373,8 @@
\texttt{sourceCpp} function will first compile the \proglang{C++} code into a
shared library and then source the embedded \proglang{R} code.
+\pagebreak
-
-
\subsection{Modifying Function Names}
You can change the name of an exported function as it appears to \proglang{R} by
@@ -393,6 +416,22 @@
specified fully).
\end{itemize}
+\subsection{Random Number Generation}
+
+\proglang{R} functions implemented in \proglang{C} or \proglang{C++} need
+to be careful to surround use of internal random number geneneration routines
+(e.g. \texttt{unif\_rand}) with calls to \texttt{GetRNGstate} and
+\texttt{PutRNGstate}.
+
+Within \pkg{Rcpp}, this is typically done using the \texttt{RNGScope} class.
+However, this is not necessary for \proglang{C++} functions exported using
+attributes because an \texttt{RNGScope} is established for them automatically.
+Note that \pkg{Rcpp} implements \texttt{RNGScope} using a counter, so it's
+still safe to execute code that may establish it's own \texttt{RNGScope} (such
+as the \pkg{Rcpp} sugar functions that deal with random number generation).
+
+\pagebreak
+
\subsection{Importing Dependencies}
It's also possible to use the \texttt{Rcpp::depends} attribute to declare
@@ -476,7 +515,13 @@
Dependencies are discovered both by scanning for package include directories
and by invoking \pkg{inline} plugins if they are available for a package.
+Note that while the \texttt{Rcpp::depends} attribute establishes dependencies
+for \texttt{sourceCpp}, it's important to note that if you include the same
+source file in an \proglang{R} package these dependencies must still be
+listed in the \texttt{Depends} and \texttt{LinkingTo} fields of the package
+\texttt{DESCRIPTION} file.
+
\subsection{Including C++ Inline}
Maintaining C++ code in it's own source file provides several benefits including
@@ -591,6 +636,31 @@
\normalsize
\end{kframe}
+\subsection{Specifying Dependencies}
+
+Once you've migrated \proglang{C++} code into a package, the dependencies for
+source files are derived from the \texttt{Depends} and \texttt{LinkingTo} fields
+in the package \texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends}
+attribute. For every package you import C++ code from (including \pkg{Rcpp})
+you need to add these entries.
+
+For example, if your package depends on \pkg{Rcpp} and \pkg{RcppArmadillo}
+you would have the following in your \texttt{DESCRIPTION} file:
+
+% \begin{verbatim}
+% Depends: Rcpp (>= 0.10.0), RcppArmadillo (>= 0.3.4.4)
+% LinkingTo: Rcpp, RcppArmadillo
+% \end{verbatim}
+\begin{kframe}
+\noindent
+\ttfamily
+\hlstd{Depends:\ Rcpp\ ($>$=\ 0.10.0),\ RcppArmadillo\ ($>$=\ 0.3.4.4)\hspace*{\fill}\\
+LinkingTo:\ Rcpp,\ RcppArmadillo}\hspace*{\fill}
+\mbox{}
+\normalfont
+\normalsize
+\end{kframe}
+
\subsection{Exporting R Functions}
Within interactive sessions you call the \texttt{sourceCpp} function
@@ -598,7 +668,7 @@
environment. However, for packages you call a single utility function to
export all \proglang{C++} functions within the package.
- The \texttt{compileAttributes} function scans the source files within a package
+The \texttt{compileAttributes} function scans the source files within a package
for export attributes and generates code as required. For example, executing
this from within the package working directory:
@@ -619,10 +689,11 @@
\begin{itemize}
\item
- \texttt{src/RcppExports.cpp} -- An \pkg{Rcpp} module that exports the functions
+ \texttt{src/RcppExports.cpp} -- The \texttt{extern "C"} wrappers required
+ to call exported \proglang{C++} functions within the package.
\item
- \texttt{R/RcppExports.R} -- The \proglang{R} code required to load the
- \pkg{Rcpp} module
+ \texttt{R/RcppExports.R} -- The \texttt{.Call} wrappers required to call
+ the \texttt{extern "C"} functions defined in \texttt{RcppExports.cpp}.
\end{itemize}
You should re-run \texttt{compileAttributes} whenever functions are added,
@@ -635,31 +706,6 @@
does not use a pattern to export functions then you should add an explicit
entry to \texttt{NAMESPACE} for each R function you want publicly available.
-\subsection{Specifying Dependencies}
-
-Once you've migrated \proglang{C++} code into a package, the dependencies for
-source files are derived from the \texttt{Depends} and \texttt{LinkingTo} fields
-in the package \texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends}
-attribute. For every package you import C++ code from (including \pkg{Rcpp})
-you need to add these entries.
-
-For example, if your package depends on \pkg{Rcpp} and \pkg{RcppArmadillo}
-you would have the following in your \texttt{DESCRIPTION} file:
-
-% \begin{verbatim}
-% Depends: Rcpp (>= 0.10.0), RcppArmadillo (>= 0.3.4.4)
-% LinkingTo: Rcpp, RcppArmadillo
-% \end{verbatim}
-\begin{kframe}
-\noindent
-\ttfamily
-\hlstd{Depends:\ Rcpp\ ($>$=\ 0.10.0),\ RcppArmadillo\ ($>$=\ 0.3.4.4)\hspace*{\fill}\\
-LinkingTo:\ Rcpp,\ RcppArmadillo}\hspace*{\fill}
-\mbox{}
-\normalfont
-\normalsize
-\end{kframe}
-
\subsection{Roxygen Comments}
The \pkg{roxygen2} package \citep{CRAN:roxygen2} provides a facility for
@@ -715,18 +761,6 @@
\normalsize
\end{kframe}
-Two notes about the R functions written to \texttt{RcppExports.R} for use with
-roxygen:
-\begin{enumerate}
-\item The generated R functions have an empty body. This is because they are
-only present for binding to roxygen comments. A call to \texttt{Rcpp::loadModule}
-will replace the empty definitions with the appropriate \proglang{C++} functions.
-\item The functions do not include argument defaults since they are
-not known at the time of generation. If you have argument defaults that you'd
-like included in the Rd usage section you can do this by adding an explicit
-\texttt{@usage} roxygen tag.
-\end{enumerate}
-
\subsection{Providing a C++ Interface}
The interface exposed from \proglang{R} packages is most typically a set of
@@ -870,32 +904,6 @@
when headers in \texttt{inst/include} change, so you should be sure to perform a
full rebuild of the package after making changes to these headers.
-\subsubsection{Binary Compatibility}
-
-An additional consideration related to exposing \proglang{C++} types from a
-package is binary compatibility. If a user of your package compiles against
-one version of the package and then runs against another version the binary
-layout of \proglang{C++} types used must remain stable in order for things to work
-correctly. Note that this is an issue that affects all \proglang{C++} interfaces
-exposed by shared libraries and is not specific to \proglang{R} packages or
-\pkg{Rcpp}. A summary of the issues presented can be found in
-`\textsl{Binary Compatibility Issues with C++}' \citep{KDE-TechBase:2012}.
-
-Note that if your package is used within a \proglang{C++} source file compiled with
-\texttt{sourceCpp} then binary compatibility is not a concern (because the
-compilation is always synchronized with the currently installed version of your
-package). Also, packages published on \texttt{CRAN} are automatically rebuilt when a
-package they depend on via \texttt{LinkingTo} is updated, so users with updated
-versions of all packages will similarly not have binary compatibility problems.
-
-However, even when installing from \texttt{CRAN} it's possible for users to
-have the latest version of one package but not of another. If you want to
-minimize binary compatibility problems even in the face of out-of-sync package
-versions then it's strongly recommended that you use only use built-in
-\proglang{C++} types and \pkg{Rcpp} wrapper types in your interfaces.
-
-\pagebreak
-
\bibliographystyle{plainnat}
\bibliography{Rcpp}
More information about the Rcpp-commits
mailing list