| Line 1... |
Line 1... |
| 1 |
% File src/library/utils/man/Rprof.Rd
|
1 |
% File src/library/utils/man/Rprof.Rd
|
| 2 |
% Part of the R package, https://www.R-project.org
|
2 |
% Part of the R package, https://www.R-project.org
|
| 3 |
% Copyright 1995-2010 R Core Team
|
3 |
% Copyright 1995-2018 R Core Team
|
| 4 |
% Distributed under GPL 2 or later
|
4 |
% Distributed under GPL 2 or later
|
| 5 |
|
5 |
|
| 6 |
\name{Rprof}
|
6 |
\name{Rprof}
|
| 7 |
\alias{Rprof}
|
7 |
\alias{Rprof}
|
| 8 |
\title{Enable Profiling of R's Execution}
|
8 |
\title{Enable Profiling of R's Execution}
|
| 9 |
\description{
|
9 |
\description{
|
| 10 |
Enable or disable profiling of the execution of \R expressions.
|
10 |
Enable or disable profiling of the execution of \R expressions.
|
| 11 |
}
|
11 |
}
|
| 12 |
\usage{
|
12 |
\usage{
|
| 13 |
Rprof(filename = "Rprof.out", append = FALSE, interval = 0.02,
|
13 |
Rprof(filename = "Rprof.out", append = FALSE, interval = 0.02,
|
| 14 |
memory.profiling = FALSE, gc.profiling = FALSE,
|
14 |
memory.profiling = FALSE, gc.profiling = FALSE,
|
| 15 |
line.profiling = FALSE, numfiles = 100L, bufsize = 10000L)
|
15 |
line.profiling = FALSE, numfiles = 100L, bufsize = 10000L)
|
| 16 |
}
|
16 |
}
|
| 17 |
\arguments{
|
17 |
\arguments{
|
| 18 |
\item{filename}{
|
18 |
\item{filename}{
|
| 19 |
The file to be used for recording the profiling results.
|
19 |
The file to be used for recording the profiling results.
|
| Line 38... |
Line 38... |
| 38 |
seconds, to the file specified. Either the \code{\link{summaryRprof}}
|
38 |
seconds, to the file specified. Either the \code{\link{summaryRprof}}
|
| 39 |
function or the wrapper script \command{R CMD Rprof} can be used to
|
39 |
function or the wrapper script \command{R CMD Rprof} can be used to
|
| 40 |
process the output file to produce a summary of the usage; use
|
40 |
process the output file to produce a summary of the usage; use
|
| 41 |
\command{R CMD Rprof --help} for usage information.
|
41 |
\command{R CMD Rprof --help} for usage information.
|
| 42 |
|
42 |
|
| - |
|
43 |
How time is measured varies by platform:
|
| - |
|
44 |
\describe{
|
| 43 |
#ifdef windows
|
45 |
\item{On Windows:}{
|
| 44 |
Exactly what the time interval measures is subtle: it is time that the
|
46 |
Exactly what the time interval measures is subtle: it is time that the
|
| 45 |
\R process is running and executing an \R command. It is not however just
|
47 |
\R process is running and executing an \R command. It is not however just
|
| 46 |
CPU time, for if \code{readline()} is waiting for input, that counts
|
48 |
CPU time, for if \code{readline()} is waiting for input, that counts
|
| 47 |
(on Windows, but not on a Unix-alike).
|
49 |
(on Windows, but not on a Unix-alike).
|
| 48 |
|
50 |
|
| 49 |
Note that the timing interval cannot be too small, for the time spent
|
51 |
Note that the timing interval cannot be too small, for the time spent
|
| 50 |
in each profiling step is added to the interval. What is feasible is
|
52 |
in each profiling step is added to the interval. What is feasible is
|
| 51 |
machine-dependent, but 10ms seemed as small as advisable on a 1GHz machine.
|
53 |
machine-dependent, but 10ms seemed as small as advisable on a 1GHz machine.
|
| 52 |
#endif
|
54 |
}
|
| 53 |
#ifdef unix
|
- |
|
| 54 |
How time is measured varies by platform: on a Unix-alike it is the CPU
|
55 |
\item{On Unix-alikes}{it is the CPU
|
| 55 |
time of the \R process, so for example excludes time when \R is waiting
|
56 |
time of the \R process, so for example excludes time when \R is waiting
|
| 56 |
for input or for processes run by \code{\link{system}} to return.
|
57 |
for input or for processes run by \code{\link{system}} to return.
|
| 57 |
|
58 |
|
| 58 |
Note that the timing interval cannot usefully be too small: once the
|
59 |
Note that the timing interval cannot usefully be too small: once the
|
| 59 |
timer goes off, the information is not recorded until the next timing
|
60 |
timer goes off, the information is not recorded until the next timing
|
| 60 |
click (probably in the range 1--10msecs).
|
61 |
click (probably in the range 1--10 ms).
|
| 61 |
#endif
|
62 |
}
|
| - |
|
63 |
}
|
| 62 |
|
64 |
|
| 63 |
Functions will only be recorded in the profile log if they put a
|
65 |
Functions will only be recorded in the profile log if they put a
|
| 64 |
context on the call stack (see \code{\link{sys.calls}}). Some
|
66 |
context on the call stack (see \code{\link{sys.calls}}). Some
|
| 65 |
\link{primitive} functions do not do so: specifically those which are
|
67 |
\link{primitive} functions do not do so: specifically those which are
|
| 66 |
of \link{type} \code{"special"} (see the \sQuote{R Internals} manual
|
68 |
of \link{type} \code{"special"} (see the \sQuote{R Internals} manual
|
| 67 |
for more details).
|
69 |
for more details).
|
| 68 |
|
70 |
|
| 69 |
Individual statements will be recorded in the profile log if
|
71 |
Individual statements will be recorded in the profile log if
|
| 70 |
\code{line.profiling} is \code{TRUE}, and if the code being executed
|
72 |
\code{line.profiling} is \code{TRUE}, and if the code being executed
|
| 71 |
was parsed with source references. See \code{\link{parse}} for a
|
73 |
was parsed with source references. See \code{\link{parse}} for a
|
| 72 |
discussion of source references. By default the statement locations
|
74 |
discussion of source references. By default the statement locations
|
| 73 |
are not shown in \code{\link{summaryRprof}}, but see that help page
|
75 |
are not shown in \code{\link{summaryRprof}}, but see that help page
|
| 74 |
for options to enable the display.
|
76 |
for options to enable the display.
|
| 75 |
}
|
77 |
}
|
| 76 |
#ifdef unix
|
- |
|
| 77 |
\note{
|
78 |
\note{
|
| - |
|
79 |
\describe{
|
| - |
|
80 |
\item{On Unix-alikes:}{
|
| 78 |
Profiling is not available on all platforms. By default,
|
81 |
Profiling is not available on all platforms. By default,
|
| 79 |
support for profiling is compiled in if possible -- configure \R with
|
82 |
support for profiling is compiled in if possible -- configure \R with
|
| 80 |
\option{--disable-R-profiling} to change this.
|
83 |
\option{--disable-R-profiling} to change this.
|
| 81 |
|
84 |
|
| 82 |
As \R profiling uses the same mechanisms as C profiling, the two
|
85 |
As \R profiling uses the same mechanisms as C profiling, the two
|
| 83 |
cannot be used together, so do not use \code{Rprof} in an executable
|
86 |
cannot be used together, so do not use \code{Rprof} in an executable
|
| 84 |
built for C-level profiling.
|
87 |
built for C-level profiling.
|
| 85 |
}
|
- |
|
| 86 |
#endif
|
88 |
}
|
| 87 |
#ifdef windows
|
89 |
\item{On Windows:}{
|
| 88 |
\note{
|
- |
|
| 89 |
\code{filename} can be a UTF-8-encoded filepath that cannot be translated to
|
90 |
\code{filename} can be a UTF-8-encoded filepath that cannot be translated to
|
| 90 |
the current locale.
|
91 |
the current locale.
|
| 91 |
}
|
92 |
}
|
| 92 |
#endif
|
93 |
}
|
| 93 |
\note{
|
94 |
|
| 94 |
The profiler interrupts R asynchronously, and it cannot allocate
|
95 |
The profiler interrupts R asynchronously, and it cannot allocate
|
| 95 |
memory to store results as it runs. This affects line profiling,
|
96 |
memory to store results as it runs. This affects line profiling,
|
| 96 |
which needs to store an unknown number of file pathnames. The
|
97 |
which needs to store an unknown number of file pathnames. The
|
| 97 |
\code{numfiles} and \code{bufsize} arguments control the size of
|
98 |
\code{numfiles} and \code{bufsize} arguments control the size of
|
| 98 |
pre-allocated buffers to hold these results: the former counts the
|
99 |
pre-allocated buffers to hold these results: the former counts the
|
| 99 |
maximum number of paths, the latter counts the numbers of bytes in
|
100 |
maximum number of paths, the latter counts the numbers of bytes in
|
| 100 |
them. If the profiler runs out of space it will skip recording the
|
101 |
them. If the profiler runs out of space it will skip recording the
|
| 101 |
line information for new files, and issue a warning when
|
102 |
line information for new files, and issue a warning when
|
| 102 |
\code{Rprof(NULL)} is called to finish profiling.
|
103 |
\code{Rprof(NULL)} is called to finish profiling.
|
The R Project SVN
R