\name{allocators}
\alias{allocatedSize}
\alias{initializeResource}
\alias{getPointer}
\alias{allocator}
\alias{allocate}
\alias{allocatedType}
\alias{deallocate}
\alias{external.size}
\alias{external.size<-}
\alias{reinitializePointer}
\title{ Generics associated with external resources and their allocators}
\description{
  These are generics used with objects of class "externalResource" and
  "externalAllocator".
}
\usage{
allocator(resource)
getPointer(resource)
initializeResource(resource, ptr, size, type, \dots)
allocatedSize(resource)
allocatedType(resource)
allocate(resource, alloc, size, type, \dots)
deallocate(resource, alloc)
external.size(resource, alloc)
external.size(resource, copy, alloc) <- value
reinitializePointer(resource, alloc)
}
\arguments{
  \item{resource}{ An object which is an "externalResource". }
  \item{alloc}{ An object which is an "externalAllocator". }
  \item{ptr}{ An external pointer. }
  \item{size}{The size - if given for a non-vector type, the numebr of
    bytes. Otherwise, the length of the vector. }
  \item{type}{Object represnting the type stored in the resource.}
  \item{copy}{Logical, if
    \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{value}{Integer, new size. }
  \item{\dots}{Further arguments passed to or from other functions.}
}
\value{
  \code{allocator} returns the allocator to be used by default with
  \code{resource}.
  
  \code{getPointer} returns the \code{"externalptr"}
  associated with \code{resource}.
  
  \code{initializeResource}
  intializes \code{resource} with \code{ptr} of type
  \code{"externalptr"} and returns \code{resource}.
      
  \code{allocatedSize} returns the 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.
  
  \code{allocatedType} returns an object representing the type to be
  stored in the resource
  
  \code{allocate} allocates the
  external pointer in resource using the allocator \code{alloc} for
  \code{resource}. If \code{type} is a basic vector object, then
  it allocates an object of same mode with length
  \code{size} and otherwise allocates \code{size} bytes of raw memory.
  The \code{resource} object is initialized by a call to
  \code{initializeResource}.

  \code{deallocate} asks the allocator \code{alloc} to
    deallocate the memory in \code{resource}. The result is
    allocator dependant.
  
  \code{external.size} returns the argument \code{size} used in the
  last call to \code{allocate} for \code{resource}.
  
  The replacement form can be used to change the size of the allocated
  memory. If \code{value} is same as \code{external.size(resource)}, then no
  action is taken. Otherwise, this reallocates the memory in
  \code{resource} using the allocator \code{alloc} (or
  \code{allocator(resource)} if \code{alloc} is missing) with new size
  \code{value} and the same type as earlier.

  \code{reinitializePointer} tries to reinitialize the memory pointer
  in resource after \code{resource} was saved and restored as an \R image
  (by serialization code, by saving the \R workspace, or by an explicit call to
  \code{save}).
}
\seealso{ \code{\link{externalAllocator-class}},
  \code{\link{externalResource-class}} }
\keyword{methods}