Class "externalResource", base class for external resource allocated by an externalAllocator

Description

Class "externalResource" is a virtual class with no slots. External allocators, represented by subclasses of class "externalAllocator" can only allocate external pointers contained in objects from a subclass of "externalResource".

Objects from the Class

A virtual Class: No objects may be created from it.

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:

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

Description of the methods:

allocatedType(resource):

Returns NULL.

allocate(resource, alloc, size, type, ...):

Allocate the external pointer in resource using the default allocator for resource. If type is a basic vector object, then allocate an object of same mode with length size. Otherwise allocate size bytes of raw memory. The resource object is initialized by a call to initializeResource.

deallocate(resource, alloc):

Ask the default allocator to deallocate the memory in resource. The result is allocator dependant.

external.size

Return the argument size used in the last call to allocate for resource

external.size<-(resource, copy, alloc, value):

If value is same as external.size(resource), then no action is taken. Otherwise, reallocate the memory in resource using the default allocator with new size value and the same type as earlier. If copy is 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.

initialize(.Object):

Code called by new("resourceSubclass", ...) if "resourceSubclass" is a subclass of "externalResource" and either has no initialize method of its own or its initialize method has callNextMethod() in its body. Returns the result of allocate(.Object, ...)

reinitializePointer(resource, alloc):

If the object resource was saved as an R image (by serialization code, by saving the R workspace, or by an explicit call to save) then the raw memory pointer in any "externalptr" object in it would be set to 0. This method tries to reinitialize the raw memory pointer. The exact result is allocator dependant.

Virtual Methods

Attempt to execute these methods would result in an error unless they have been redefined for a subclass of "externalResource".

Signature components for implementation of the methods:

Description of the virtual methods:

allocatedSize(resource):

Size of memory to be allocated for resource. If 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.

allocator(resource):

The allocator to be used by default with this resource.

getPointer(reource):

Return the "externalptr" associated with this resource.

initializeResource(resource, ptr, size, type, ...):

Intialize resource with ptr of type "externalptr". The size and type arguments are identical to that obtained from previous calls to allocatedSize(resource) and allocatedType(resource).

Other Virtual Methods

These methods must be redefined for subclasses for "externalAllocator". It is not necessary to define them for specific subclasses of "externalResource".

Signature components for implementation of the methods:

Description of the virtual methods:

allocate(resource, alloc, size, type, ...):

Allocate the external pointer in resource using the allocator alloc.

deallocate(resource, alloc):

Ask the allocator alloc to deallocate the memory in resource.

external.size

Return the size of the allocated memory in resource.

external.size<-(resource, copy, alloc, value):

Reallocate the memory in resource using the allocator alloc.

reinitializePointer(resource, alloc):

If the raw memory pointer in resource is zero, try to reinitialize it.

Author(s)

Saikat DebRoy <saikat@stat.wisc.edu>

See Also

externalAllocator-class for more details on how to use an allocator with objects from subclasses of "externalResource".

gcAllocator-class for an example of a simple subclass of "externalResource".

setVirtualMethod for more on virtual methods.