\name{gcAllocator-class}
\docType{class}
\alias{gcAllocator-class}
\alias{allocate,externalResource,gcAllocator-method}
\alias{deallocate,externalResource,gcAllocator-method}
\alias{external.size,externalResource,gcAllocator-method}
\alias{external.size<-,externalResource,logical,gcAllocator,numeric-method}
\alias{reinitializePointer,externalResource,gcAllocator-method}

\title{Class "gcAllocator", memory allocator class for external resources }
\description{ A memory allocator class for external resources that
  allocates memory using R memory management system. The allocated
  memory is freed by the R garbage collector when all refernce to it is
  removed. }
\section{Objects from the Class}{
Objects can be created by calls of the form \code{new("gcAllocator")}.
}
\section{Extends}{
Class \code{"externalAllocator"}, directly.
}
\section{Methods}{
  Signature components for the methods:

  \tabular{ll}{
    resource \tab The class "externalResource"\cr
    alloc \tab The class of "gcAllocator"\cr
    size \tab The class "ANY"\cr
    type \tab The class "ANY"\cr
    copy \tab The class "logical"\cr
    value \tab The class "ANY"\cr
  }

  Description of the methods:

  \describe{
      \item{allocate(resource, alloc, size, type, \dots):}{ Allocate the
	external pointer in \code{resource}.
	If \code{type} is a basic vector object, then
	allocate an object of same mode with length
	\code{size}. Otherwise allocate \code{size} bytes of raw
	memory. The allocation is done by creating an R basic vector
	with same class as type and storing it in the protected field of
	the newly created external pointer. Ends with a call to
	\code{initializeResource} to initialize the \code{resource}
        object. }
      \item{deallocate(resource, alloc):}{ Replace the protected field
	of \code{resource@ptr} with \code{R_NilValue}. }
      \item{external.size}{ Return the size of the allocated memory in
	\code{resource}. }
      \item{external.size<-(resource, copy, alloc, value):}{ If
	\code{value} is same as \code{external.size(resource)}, then no
	action is taken. Otherwise, reallocate the memory in
	\code{resource} with new size \code{value}. If \code{copy} is
	\code{TRUE} (the default), then the new memory is initialized to
	the content of the old memory for the minimum of old and new
	sizes. Content of any uninitialized memory is undefined. }
      \item{reinitializePointer(resource, alloc):}{ If the object
	\code{resource} was saved as an \R image (by serialization
	code, by saving the \R workspace, or by an explicit call to
	\code{save}) then the raw memory pointer in any
	\code{"externalptr"} object in it would be set to \code{0}. This
	method reinitializes the memory (if possible) by using the
      protected field of the external pointer. }
  }
}
\examples{
library(externalVector)
## set a storage class
setClass("testStorage",
         representation(ptr="externalptr"),
         contains="externalResource")
setMethod("initializeResource", "testStorage",
          function(resource, ptr, size, type, \dots)
       {
           resource@ptr <- ptr
           resource
       })
setMethod("allocator", "testStorage",
          function(resource)
          new("gcAllocator"))
setMethod("getPointer", "testStorage",
          function(resource)
          resource@ptr)
setMethod("allocatedSize", "testStorage",
          function(resource)
          32)
## Now create an object from the class
x <- new("testStorage")
x
external.size(x)
external.size(x) <- 64
x
external.size(x)
deallocate(x)
x
external.size(x)
}
\keyword{classes}