The R Project SVN R

% File src/library/methods/man/refClass.Rd

% Part of the R package, https://www.R-project.org

% Copyright 2010-2013 R Core Team

% Distributed under GPL 2 or later

\name{LocalReferenceClasses}

\title{Localized Objects based on Reference Classes}

\alias{LocalReferenceClasses}

\alias{localRefClass-class}

\alias{$<-,localRefClass-method} %$

\description{

Local reference classes are modified \link{ReferenceClasses} that

isolate the objects to the local frame.  Therefore, they do \emph{not}

propagate changes back to the calling environment.   At the same time,

they use the reference field semantics locally, avoiding the automatic

duplication applied to standard \R objects.

The current implementation has no special construction.  To create a

local reference class, call \code{\link{setRefClass}()} with a

\code{contains=} argument that includes \code{"localRefClass"}.  See

the example below.

Local reference classes operate essentially as do regular, functional

classes in \R; that is, changes are made by assignment and take place

in the local frame.

The essential difference is that replacement operations (like the

change to the \code{twiddle} field in the example) do not cause

duplication of the entire object, as would be the case for a formal

class or for data with attributes or in a named list.

The purpose is to allow large objects in some fields that are not

changed along with potentially frequent changes to other fields, but

without copying the large fields.

}

\usage{

\special{setRefClass(Class, fields = , contains = c("localRefClass",....),

     methods =, where =, ...)}

}

\details{

Localization of objects is only partially automated in the current implementation.

Replacement expressions using the \code{$<-} operator are safe. %$

However, if reference methods for the class themselves modify fields,

using \code{<<-}, for example, then 

one must ensure that the object is local to the relevant frame before

any such method is called.

Otherwise, standard reference class behavior still prevails.

There are two ways to ensure locality.  The direct way is to invoke

the special

method \code{x$ensureLocal()} on the object.

The other way is to modify a field explicitly by \code{x$field <- ...}

It's

only necessary that  one or the other of these happens

once for each object, in order to trigger the shallow copy that

provides locality for the references.  In the example below, we show

both mechanisms.

However it's done, localization must occur

\emph{before} any methods make changes.  (Eventually, some use of code

tools should at least largely automate this process, although it may

be difficult to guarantee success under arbitrary circumstances.)

}

\author{

  John Chambers

}

\examples{

## class "myIter" has a BigData field for the real (big) data

## and a "twiddle" field for some parameters that it twiddles

## ( for some reason)

myIter <- setRefClass("myIter", contains = "localRefClass",

  fields = list(BigData = "numeric", twiddle = "numeric"))

tw <- rnorm(3)

x1 <- myIter(BigData = rnorm(1000), twiddle = tw) # OK, not REALLY big

twiddler <- function(x, n) {

  x$ensureLocal() # see the Details.  Not really needed in this example

  for(i in seq(length = n)) {

      x$twiddle <- x$twiddle + rnorm(length(x$twiddle))

      ## then do something ....

      ## Snooping in gdb, etc will show that x$BigData is not copied

  }

  return(x)

}

x2 <- twiddler(x1, 10)

stopifnot(identical(x1$twiddle, tw), !identical(x1$twiddle, x2$twiddle))

}

\keyword{ programming }

\keyword{ classes }