\Header{Memory}{Memory Available for Data Storage}
\alias{mem.limits}{Memory}
\keyword{environment}{Memory}
\begin{Description}\relax
Use command line options to control the memory available for \R.
\end{Description}
\begin{Usage}
\begin{verbatim}
R --min-vsize=vl --max-vsize=vu --min-nsize=nl --max-nsize=nu

mem.limits(nsize = NA, vsize = NA)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{vl, vu, vsize}] Heap memory in bytes.
\item[\code{nl, nu, nsize}] Number of cons cells.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\R{} has a variable-sized workspace (from version 1.2.0). There is now
much less need to set memory options than previously, and most
users will never need to set these.  They are provided both as a way
to control the overall memory usage (which can also be done
by operating-system facilities such as \code{limit} on Unix),
and since setting larger values of the minima will make \R{} slightly
more efficient on large tasks.


To understand the options, one needs to know that \R{} maintains
separate areas for fixed and variable sized objects.  The first of these
is allocated as an array of \dQuote{\emph{cons cells}} (Lisp programmers will
know what they are, others may think of them as the building blocks of
the language itself, parse trees, etc.), and the second are thrown on a
\dQuote{\emph{heap}} of \dQuote{Vcells} of 8 bytes each.  Effectively,
the input \code{v} is rounded up to the nearest multiple of 8.

Each cons cell occupies 28 bytes on a 32-bit machine, (usually) 56 bytes
on a 64-bit machine.

The \option{--*-nsize} options can be used to specify the number of
cons cells and the \option{--*-vsize} options specify the size of the
vector heap in bytes.  Both options must be integers or integers
followed by \code{G}, \code{M}, \code{K}, or \code{k} meaning
\code{Giga} (\eqn{2^{30} = 1073741824}{}) \emph{Mega} (\eqn{2^{20} =
1048576}{}), (computer) \emph{Kilo} (\eqn{2^{10} = 1024}{}), or regular
\emph{kilo} (1000).

The \option{--min-*} options set the minimal sizes for the number of
cons cells and for the vector heap.  These values are also the initial
values, but thereafter \R{} will grow or shrink the areas depending on
usage, but never exceeding the limits set by the \option{--max-*}
options nor decreasing below the initial values.

The default values are currently minima of 350k cons cells,
6Mb of vector heap
and no maxima (other than machine resources). The maxima can be
changed during an \R{} session by calling \code{mem.limits}. (If this is
called with the default values, it reports the current settings.)


You can find out the current memory consumption (the heap and cons
cells used as numbers and megabytes) by typing \code{\Link{gc}()} at the
\R{} prompt.  Note that following \code{\Link{gcinfo}(TRUE)}, automatic
garbage collection always prints memory use statistics.  Maxima will
never be reduced below the current values for triggering garbage
collection, and attempts to do so will be silently ignored.


When using \code{\Link{read.table}}, the memory requirements are in
fact higher than anticipated, because the file is first read in as one
long string which is then split again.  Use \code{\Link{scan}} if
possible in case you run out of memory when reading in a large table.
\end{Details}
\begin{Value}
\code{mem.limits()} returns an integer vector giving the current
settings of the maxima, possibly \code{NA}.
\end{Value}
\begin{Note}\relax
For backwards compatibility, options \option{--nsize} and
\option{--vsize} are equivalent to \option{--min-nsize} and
\option{--min-vsize}.
\end{Note}
\begin{SeeAlso}\relax
\code{\Link{gc}} for information on the garbage collector,
\code{\Link{object.size}(a)} for the (approximate) size of \R{} object
\code{a}.  \code{\Link{memory.profile}} for profiling the usage of
cons cells.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# Start R with 10MB of heap memory and 500k cons cells, limit to
# 100Mb and 1M cells
## Not run: 
## Unix
R --min-vsize=10M --max-vsize=100M --min-nsize=500k --max-nsize=1M
## End(Not run)
\end{ExampleCode}
\end{Examples}

