gctorture.Rd 2.08 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/gctorture.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2007 R Core Team
Radford Neal's avatar
Radford Neal committed
4
% Modifications for pqR Copyright (c) 2018 Radford M. Neal.
Radford Neal's avatar
Radford Neal committed
5 6 7 8 9 10
% Distributed under GPL 2 or later

\name{gctorture}
\title{Torture Garbage Collector}
\usage{
gctorture(on = TRUE)
Radford Neal's avatar
Radford Neal committed
11
gctorture2(step, wait = step, inhibit_release = FALSE)
Radford Neal's avatar
Radford Neal committed
12 13
}
\alias{gctorture}
Radford Neal's avatar
Radford Neal committed
14
\alias{gctorture2}
Radford Neal's avatar
Radford Neal committed
15 16
\arguments{
  \item{on}{logical; turning it on/off.}
Radford Neal's avatar
Radford Neal committed
17 18 19 20 21 22
  \item{step}{integer; run GC every \code{step} allocations; \code{step
      = 0} turns the GC torture off.}
  \item{wait}{integer; number of allocations to wait before starting
    GC torture.}
  \item{inhibit_release}{logical; do not release free objects for
    re-use: use with caution.}
Radford Neal's avatar
Radford Neal committed
23 24 25 26 27 28
}
\description{
  Provokes garbage collection on (nearly) every memory allocation.
  Intended to ferret out memory protection bugs.  Also makes \R run
  \emph{very} slowly, unfortunately.
}
Radford Neal's avatar
Radford Neal committed
29 30
\details{
  Calling \code{gctorture(TRUE)} instructs the memory manager to force a
Radford Neal's avatar
Radford Neal committed
31
  full GC on every allocation. 
Radford Neal's avatar
Radford Neal committed
32

Radford Neal's avatar
Radford Neal committed
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
  \code{gctorture2} provides a more refined interface that allows the
  start of the GC torture to be deferred and also gives the option of
  running a GC only every \code{step} allocations.  

  A \code{TRUE} value for the \code{inhibit_release} argument of
  \code{gctorture2} prevents free objects from being re-used.  This
  will cause memory to grow and should be used with caution and in
  conjunction with operating system facilities to monitor and limit
  process memory use.  It is most useful if options have been set when
  building pqR that cause memory in freed objects to be overwritten
  with values that are likely to cause an error if the object is
  mistakenly referenced after being freed.

  Environment variables can also be used to turn on GC torture:
  \code{R_GCTORTURE} corresponds to the \code{step} argument to
48
  \code{gctorture2}, \code{R_GCTORTURE_WAIT} to \code{wait}, and
Radford Neal's avatar
Radford Neal committed
49
  \code{R_GCTORTURE_INHIBIT_RELEASE} to \code{inhibit_release}.
Radford Neal's avatar
Radford Neal committed
50
}
Radford Neal's avatar
Radford Neal committed
51

Radford Neal's avatar
Radford Neal committed
52
\value{
Radford Neal's avatar
Radford Neal committed
53
  Previous value of first argument.
Radford Neal's avatar
Radford Neal committed
54
}
Radford Neal's avatar
Radford Neal committed
55
\author{Peter Dalgaard and Luke Tierney}
Radford Neal's avatar
Radford Neal committed
56 57
\keyword{environment}