\HeaderA{Rprof}{Enable Profiling of R's Execution}{Rprof}
\keyword{utilities}{Rprof}
\begin{Description}\relax
Enable or disable profiling of the execution of \R{} expressions.
\end{Description}
\begin{Usage}
\begin{verbatim}
Rprof(filename = "Rprof.out", append = FALSE, interval = 0.02,
       memory.profiling=FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{filename}] The file to be used for recording the profiling results.
Set to \code{NULL} or \code{""} to disable profiling.

\item[\code{append}] logical: should the file be over-written or appended to?

\item[\code{interval}] real: time interval between samples.

\item[\code{memory.profiling}] logical: write memory use information to the file?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Enabling profiling automatically disables any existing profiling to
another or the same file.

Profiling works by writing out the call stack every \code{interval}
seconds, to the file specified.  Either the \code{\LinkA{summaryRprof}{summaryRprof}}
function or the Perl script \code{R CMD Rprof} can be used to process
the output file to produce a summary of the
usage; use \code{R CMD Rprof --help} for usage information.

How time is measured varies by platform: on a Unix-alike it is the CPU
time of the \R{} process, so for example excludes time when \R{} is waiting
for input or for processes run by \code{\LinkA{system}{system}} to return.

Note that the timing interval cannot usefully be too small: once the
timer goes off, the information is not recorded until the next timing
click (probably in the range 1--10msecs).

Functions will only be recorded in the profile log if they put a
context on the call stack (see \code{\LinkA{sys.calls}{sys.calls}}).  Some
\LinkA{primitive}{primitive} functions do not do so: specifically those which are
of \LinkA{type}{type} \code{"special"} (see the \sQuote{R Internals} manual
for more details).
\end{Details}
\begin{Note}\relax
Profiling is not available on all platforms.  By default, it is
attempted to compile support for profiling.  Configure \R{} with
\option{--disable-R-profiling} to change this.

As \R{} profiling uses the same mechanisms as C profiling, the two
cannot be used together, so do not use \code{Rprof} in an executable
built for profiling.
\end{Note}
\begin{SeeAlso}\relax
The chapter on \dQuote{Tidying and profiling R code} in
\dQuote{Writing \R{} Extensions} (see the \file{doc/manual} subdirectory
of the \R{} source tree).

\code{\LinkA{summaryRprof}{summaryRprof}}

\code{\LinkA{tracemem}{tracemem}}, \code{\LinkA{Rprofmem}{Rprofmem}} for other ways to track
memory use.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
Rprof()
## some code to be profiled
Rprof(NULL)
## some code NOT to be profiled
Rprof(append=TRUE)
## some code to be profiled
Rprof(NULL)
...
## Now post-process the output as described in Details
## End(Not run)\end{ExampleCode}
\end{Examples}

