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

\title{Class "externalAllocator", base class for memory allocators for
  external resources }
\description{ Class \code{"externalAllocator"} is a virtual class with no
  slots. It represents memory allocators that allocate raw memory to be
  held in an object of class \code{"externalptr"}. Instead of returning the
  \code{"externalptr"} object directly, the allocators deal with
  subclasses of \code{"externalResource"} that hold an object of
  class \code{"externalptr"}. }
\section{Objects from the Class}{A virtual Class: No objects may be created from it.}
\section{Virtual Methods}{
  Attempt to execute these methods would result in an error unless they
  have been redefined for a subclass of \code{"externalAllocator"}.

  Signature components for implementation of the methods:

  \tabular{ll}{
    resource \tab The class "externalResource"\cr
    alloc \tab A subclass of "externalAllocator"\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 virtual methods:

  \describe{
      \item{allocate(resource, alloc, size, type, \dots):}{ Allocate the
	external pointer in \code{resource} using the allocator
	\code{alloc}. 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. This method should end with a call to
	\code{initializeResource} to initialize the \code{resource}
        object. }
      \item{deallocate(resource, alloc):}{ The allocator \code{alloc}
	should try to dealloacte the raw memory in \code{resource}. It
	should not modify the \code{resource} object in any way other
	than modifying the object of class \code{"externalptr"} in
	\code{resource} to reflect the deallocation. }
      \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} using the allocator \code{alloc} 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 tries to reinitialize the raw memory pointer. The exact
	result is allocator dependant. }
  }
}
\author{ Saikat DebRoy \email{<saikat@stat.wisc.edu>} }
\seealso{
  \code{\link{externalResource-class}} for more on how to
  use an allocator with objects from subclasses of
  \code{"externalResource"}.

  \code{\link{gcAllocator-class}} for an example of a
  subclass of \code{"externalAllocator"}.

  \code{\link{setVirtualMethod}} for more on virtual methods.
}
\keyword{classes}
\keyword{methods}