\name{externalResource-class}
\docType{class}
\alias{externalResource-class}
\alias{allocate,externalResource,missing-method}
\alias{allocatedSize,externalResource-method}
\alias{allocatedType,externalResource-method}
\alias{allocator,externalResource-method}
\alias{deallocate,externalResource,missing-method}
\alias{external.size,externalResource,missing-method}
\alias{external.size<-,externalResource,ANY,missing,ANY-method}
\alias{getPointer,externalResource-method}
\alias{initialize,externalResource-method}
\alias{initializeResource,externalResource,externalptr-method}
\alias{reinitializePointer,externalResource,missing-method}

\title{Class "externalResource", base class for external resource
  allocated by an externalAllocator }
\description{ Class \code{"externalResource"} is a virtual class with no
  slots. External allocators, represented by subclasses of class
  \code{"externalAllocator"} can only allocate external pointers
  contained in objects from a subclass of \code{"externalResource"}. }
\section{Objects from the Class}{A virtual Class: No objects may be created from it.}
\section{Methods for the virtual class "externalResource"}{
  These methods are defined for the virtual class "externalResource" and
  need not be redefined by its subclasses.

  Signature components for the methods are:

  \tabular{ll}{
    resource \tab The class "externalResource"\cr
    alloc \tab The class "missing"\cr
    ptr \tab The class "externalptr"\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
  }

  The argument \code{alloc} has the class "missing" wherever it appears
  in these methods. That means, to invoke these methods, the argument
  \code{alloc} must be ommitted from the call and to use any of the
  additional arguments, they must be specfied by name.
  For example, use \code{allocate(resource, size=size, type=type)}
  and not \code{allocate(resource, size, type)}.

  Description of the methods:
  
  \describe{
      \item{allocatedType(resource):}{ Returns \code{NULL}. }
      \item{allocate(resource, alloc, size, type, \dots):}{ Allocate the
	external pointer in resource using the default allocator for
	\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 \code{resource} object is initialized by a call to
	\code{initializeResource}. }
      \item{deallocate(resource, alloc):}{ Ask the default allocator to
	deallocate the memory in \code{resource}. The result is
	allocator dependant. }
      \item{external.size}{ Return the argument \code{size} used in the
	last call to \code{allocate} for \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 default allocator with new size
	\code{value} and the same type as earlier. 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. Under any circumstance,
	the inherent type of the allocated memory remains the same as
	its initial value. }
      \item{initialize(.Object):}{ Code called by
	new("resourceSubclass", \dots) if "resourceSubclass" is a subclass
	of "externalResource" and either has no \code{initialize} method
	of its own or its \code{initialize} method has
	\code{callNextMethod()} in its body. Returns the result of
	\code{allocate(.Object, \dots)}}
      \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. }
  }
}
\section{Virtual Methods}{
  Attempt to execute these methods would result in an error unless they
  have been redefined for a subclass of \code{"externalResource"}.

  Signature components for implementation of the methods:

  \tabular{ll}{
    resource \tab A subclass of "externalResource"\cr
    ptr \tab The class "externalptr"\cr
    size \tab The class "ANY"\cr
    type \tab The class "ANY"\cr
  }

  Description of the virtual methods:
  
  \describe{
      \item{allocatedSize(resource):}{ Size of memory to be allocated for
	\code{resource}. If \code{allocatedType(resource)} is
	an \R basic vector type, then the size is the length of the
	vector. Otherwise the size is the total number of bytes. }
      \item{allocator(resource):}{ The allocator to be used by default with
	this \code{resource}. }
      \item{getPointer(reource):}{ Return the \code{"externalptr"}
	associated with this \code{resource}. }
      \item{initializeResource(resource, ptr, size, type, \dots):}{
	Intialize \code{resource} with \code{ptr} of type
	\code{"externalptr"}. The \code{size} and \code{type} arguments are
	identical to that obtained from previous calls to
	\code{allocatedSize(resource)} and \code{allocatedType(resource)}. }
    }
}
\section{Other Virtual Methods}{
  These methods must be redefined for subclasses for
  \code{"externalAllocator"}. It is not necessary to define them for
  specific subclasses of \code{"externalResource"}.

  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}. }
      \item{deallocate(resource, alloc):}{ Ask the allocator \code{alloc}
	to deallocate the memory in \code{resource}. }
      \item{external.size}{ Return the size of the allocated memory in
	\code{resource}. }
      \item{external.size<-(resource, copy, alloc, value):}{ Reallocate
	the memory in \code{resource} using the allocator \code{alloc}. }
      \item{reinitializePointer(resource, alloc):}{ If the raw memory
	pointer in \code{resource} is zero, try to reinitialize it. }
  }
}
\author{ Saikat DebRoy \email{<saikat@stat.wisc.edu>} }
\seealso{
  \code{\link{externalAllocator-class}} for more details on how to
  use an allocator with objects from subclasses of
  \code{"externalResource"}.

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

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