Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public class

Allocation

extends BaseObj
java.lang.Object
   ↳ android.support.v8.renderscript.BaseObj
     ↳ android.support.v8.renderscript.Allocation

Class Overview

This class provides the primary method through which data is passed to and from RenderScript kernels. An Allocation provides the backing store for a given Type .

An Allocation also contains a set of usage flags that denote how the Allocation could be used. For example, an Allocation may have usage flags specifying that it can be used from a script as well as input to a Sampler . A developer must synchronize across these different usages using syncAll(int) in order to ensure that different users of the Allocation have a consistent view of memory. For example, in the case where an Allocation is used as the output of one kernel and as Sampler input in a later kernel, a developer must call syncAll(Allocation.USAGE_SCRIPT) prior to launching the second kernel to ensure correctness.

An Allocation can be populated with the copyFrom(Bitmap) routines. For more complex Element types, the copyFromUnchecked(byte[]) methods can be used to copy from byte arrays or similar constructs.

Developer Guides

For more information about creating an application that uses RenderScript, read the RenderScript developer guide.

Summary

Nested Classes
enum Allocation.MipmapControl Controls mipmap behavior when using the bitmap creation and update functions. 
Constants
int USAGE_GRAPHICS_TEXTURE The Allocation will be used as a texture source by one or more graphics programs.
int USAGE_IO_INPUT The Allocation will be used as a SurfaceTexture consumer.
int USAGE_IO_OUTPUT The Allocation will be used as a SurfaceTexture producer.
int USAGE_SCRIPT The Allocation will be bound to and accessed by scripts.
int USAGE_SHARED The Allocation's backing store will be inherited from another object (usually a Bitmap ); copying to or from the original source Bitmap will cause a synchronization rather than a full copy.
Public Methods
void copy1DRangeFrom (int off, int count, float[] d)
Copy an array into part of this Allocation.
void copy1DRangeFrom (int off, int count, short[] d)
Copy an array into part of this Allocation.
void copy1DRangeFrom (int off, int count, int[] d)
Copy an array into part of this Allocation.
void copy1DRangeFrom (int off, int count, Allocation data, int dataOff)
Copy part of an Allocation into this Allocation.
void copy1DRangeFrom (int off, int count, byte[] d)
Copy an array into part of this Allocation.
void copy1DRangeFromUnchecked (int off, int count, byte[] d)
Copy an array into part of this Allocation.
void copy1DRangeFromUnchecked (int off, int count, short[] d)
Copy an array into part of this Allocation.
void copy1DRangeFromUnchecked (int off, int count, float[] d)
Copy an array into part of this Allocation.
void copy1DRangeFromUnchecked (int off, int count, int[] d)
Copy an array into part of this Allocation.
void copy2DRangeFrom (int xoff, int yoff, int w, int h, float[] data)
Copy from an array into a rectangular region in this Allocation.
void copy2DRangeFrom (int xoff, int yoff, int w, int h, byte[] data)
Copy from an array into a rectangular region in this Allocation.
void copy2DRangeFrom (int xoff, int yoff, int w, int h, int[] data)
Copy from an array into a rectangular region in this Allocation.
void copy2DRangeFrom (int xoff, int yoff, int w, int h, short[] data)
Copy from an array into a rectangular region in this Allocation.
void copy2DRangeFrom (int xoff, int yoff, Bitmap data)
Copy a Bitmap into an Allocation.
void copy2DRangeFrom (int xoff, int yoff, int w, int h, Allocation data, int dataXoff, int dataYoff)
Copy a rectangular region from an Allocation into a rectangular region in this Allocation.
void copyFrom (byte[] d)
Copy into this Allocation from an array.
void copyFrom (int[] d)
Copy into this Allocation from an array.
void copyFrom (float[] d)
Copy into this Allocation from an array.
void copyFrom ( BaseObj[] d)
Copy an array of RS objects to the Allocation.
void copyFrom ( Allocation a)
Copy an Allocation from an Allocation.
void copyFrom ( Bitmap b)
Copy into an Allocation from a Bitmap .
void copyFrom (short[] d)
Copy into this Allocation from an array.
void copyFromUnchecked (int[] d)
Copy into this Allocation from an array.
void copyFromUnchecked (short[] d)
Copy into this Allocation from an array.
void copyFromUnchecked (byte[] d)
Copy into this Allocation from an array.
void copyFromUnchecked (float[] d)
Copy into this Allocation from an array.
void copyTo (byte[] d)
Copy from the Allocation into a byte array.
void copyTo (int[] d)
Copy from the Allocation into a int array.
void copyTo (float[] d)
Copy from the Allocation into a float array.
void copyTo (short[] d)
Copy from the Allocation into a short array.
void copyTo ( Bitmap b)
Copy from the Allocation into a Bitmap .
static Allocation createCubemapFromBitmap ( RenderScript rs, Bitmap b)
Creates a non-mipmapped cubemap Allocation for use as a graphics texture from a Bitmap containing the horizontal list of cube faces.
static Allocation createCubemapFromBitmap ( RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)
Creates a cubemap Allocation from a Bitmap containing the horizontal list of cube faces.
static Allocation createCubemapFromCubeFaces ( RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg, Allocation.MipmapControl mips, int usage)
Creates a cubemap Allocation from 6 Bitmap objects containing the cube faces.
static Allocation createCubemapFromCubeFaces ( RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg)
Creates a non-mipmapped cubemap Allocation for use as a sampler input from 6 Bitmap objects containing the cube faces.
static Allocation createFromBitmap ( RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)
Creates an Allocation from a Bitmap .
static Allocation createFromBitmap ( RenderScript rs, Bitmap b)
Creates an Allocation from a Bitmap .
static Allocation createFromBitmapResource ( RenderScript rs, Resources res, int id)
Creates a non-mipmapped Allocation to use as a graphics texture from the Bitmap referenced by resource ID.
static Allocation createFromBitmapResource ( RenderScript rs, Resources res, int id, Allocation.MipmapControl mips, int usage)
Creates an Allocation from the Bitmap referenced by resource ID.
static Allocation createFromString ( RenderScript rs, String str, int usage)
Creates an Allocation containing string data encoded in UTF-8 format.
static Allocation createSized ( RenderScript rs, Element e, int count, int usage)
Creates an Allocation with a specified number of given elements
static Allocation createSized ( RenderScript rs, Element e, int count)
Creates an Allocation with a specified number of given elements
static Allocation createTyped ( RenderScript rs, Type type, int usage)
Creates an Allocation with the size specified by the type and no mipmaps generated by default
static Allocation createTyped ( RenderScript rs, Type type)
Creates an Allocation for use by scripts with a given Type and no mipmaps
static Allocation createTyped ( RenderScript rs, Type type, Allocation.MipmapControl mips, int usage)
Creates a new Allocation with the given Type , mipmap flag, and usage flags.
void generateMipmaps ()
Generate a mipmap chain.
int getBytesSize ()
Get the size of the Allocation in bytes.
Element getElement ()
Get the Element of the Type of the Allocation.
Type getType ()
Get the Type of the Allocation.
int getUsage ()
Get the usage flags of the Allocation.
void ioReceive ()
Receive the latest input into the Allocation.
void ioSend ()
Send a buffer to the output stream.
void setFromFieldPacker (int xoff, FieldPacker fp)
This is only intended to be used by auto-generated code reflected from the RenderScript script files and should not be used by developers.
void setFromFieldPacker (int xoff, int component_number, FieldPacker fp)
This is only intended to be used by auto-generated code reflected from the RenderScript script files.
void syncAll (int srcLocation)
Propagate changes from one usage of the Allocation to the other usages of the Allocation.
Protected Methods
void finalize ()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class android.support.v8.renderscript.BaseObj
From class java.lang.Object

Constants

public static final int USAGE_GRAPHICS_TEXTURE

The Allocation will be used as a texture source by one or more graphics programs.

Constant Value: 2 (0x00000002)

public static final int USAGE_IO_INPUT

The Allocation will be used as a SurfaceTexture consumer. This usage will cause the Allocation to be created as read-only.

Constant Value: 32 (0x00000020)

public static final int USAGE_IO_OUTPUT

The Allocation will be used as a SurfaceTexture producer. The dimensions and format of the SurfaceTexture will be forced to those of the Allocation.

Constant Value: 64 (0x00000040)

public static final int USAGE_SCRIPT

The Allocation will be bound to and accessed by scripts.

Constant Value: 1 (0x00000001)

public static final int USAGE_SHARED

The Allocation's backing store will be inherited from another object (usually a Bitmap ); copying to or from the original source Bitmap will cause a synchronization rather than a full copy. syncAll(int) may also be used to synchronize the Allocation and the source Bitmap.

This is set by default for allocations created with createFromBitmap(RenderScript, Bitmap) in API version 18 and higher.

Constant Value: 128 (0x00000080)

Public Methods

public void copy1DRangeFrom (int off, int count, float[] d)

Copy an array into part of this Allocation. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit float type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array.

public void copy1DRangeFrom (int off, int count, short[] d)

Copy an array into part of this Allocation. This variant is type checked and will generate exceptions if the Allocation type is not a 16 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFrom (int off, int count, int[] d)

Copy an array into part of this Allocation. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFrom (int off, int count, Allocation data, int dataOff)

Copy part of an Allocation into this Allocation.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
data the source data allocation.
dataOff off The offset of the first element in data to be copied.

public void copy1DRangeFrom (int off, int count, byte[] d)

Copy an array into part of this Allocation. This variant is type checked and will generate exceptions if the Allocation type is not an 8 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, byte[] d)

Copy an array into part of this Allocation. This method does not guarantee that the Allocation is compatible with the input buffer.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, short[] d)

Copy an array into part of this Allocation. This method does not guarantee that the Allocation is compatible with the input buffer.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, float[] d)

Copy an array into part of this Allocation. This method does not guarantee that the Allocation is compatible with the input buffer.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, int[] d)

Copy an array into part of this Allocation. This method does not guarantee that the Allocation is compatible with the input buffer.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, float[] data)

Copy from an array into a rectangular region in this Allocation. The array is assumed to be tightly packed.

Parameters
xoff X offset of the region to update in this Allocation
yoff Y offset of the region to update in this Allocation
w Width of the region to update
h Height of the region to update
data to be placed into the Allocation

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, byte[] data)

Copy from an array into a rectangular region in this Allocation. The array is assumed to be tightly packed.

Parameters
xoff X offset of the region to update in this Allocation
yoff Y offset of the region to update in this Allocation
w Width of the region to update
h Height of the region to update
data to be placed into the Allocation

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, int[] data)

Copy from an array into a rectangular region in this Allocation. The array is assumed to be tightly packed.

Parameters
xoff X offset of the region to update in this Allocation
yoff Y offset of the region to update in this Allocation
w Width of the region to update
h Height of the region to update
data to be placed into the Allocation

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, short[] data)

Copy from an array into a rectangular region in this Allocation. The array is assumed to be tightly packed.

Parameters
xoff X offset of the region to update in this Allocation
yoff Y offset of the region to update in this Allocation
w Width of the region to update
h Height of the region to update
data to be placed into the Allocation

public void copy2DRangeFrom (int xoff, int yoff, Bitmap data)

Copy a Bitmap into an Allocation. The height and width of the update will use the height and width of the Bitmap .

Parameters
xoff X offset of the region to update in this Allocation
yoff Y offset of the region to update in this Allocation
data the Bitmap to be copied

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, Allocation data, int dataXoff, int dataYoff)

Copy a rectangular region from an Allocation into a rectangular region in this Allocation.

Parameters
xoff X offset of the region in this Allocation
yoff Y offset of the region in this Allocation
w Width of the region to update.
h Height of the region to update.
data source Allocation.
dataXoff X offset in source Allocation
dataYoff Y offset in source Allocation

public void copyFrom (byte[] d)

Copy into this Allocation from an array. This variant is type checked and will generate exceptions if the Allocation's Element is not an 8 bit integer type.

Parameters
d the source data array

public void copyFrom (int[] d)

Copy into this Allocation from an array. This variant is type checked and will generate exceptions if the Allocation's Element is not a 32 bit integer type.

Parameters
d the source data array

public void copyFrom (float[] d)

Copy into this Allocation from an array. This variant is type checked and will generate exceptions if the Allocation's Element is not a 32 bit float type.

Parameters
d the source data array

public void copyFrom ( BaseObj[] d)

Copy an array of RS objects to the Allocation.

Parameters
d Source array.

public void copyFrom ( Allocation a)

Copy an Allocation from an Allocation. The types of both allocations must be identical.

Parameters
a the source allocation

public void copyFrom ( Bitmap b)

Copy into an Allocation from a Bitmap . The height, width, and format of the bitmap must match the existing allocation.

If the Bitmap is the same as the Bitmap used to create the Allocation with createFromBitmap(RenderScript, Bitmap) and USAGE_SHARED is set on the Allocation, this will synchronize the Allocation with the latest data from the Bitmap , potentially avoiding the actual copy.

Parameters
b the source bitmap

public void copyFrom (short[] d)

Copy into this Allocation from an array. This variant is type checked and will generate exceptions if the Allocation's Element is not a 16 bit integer type.

Parameters
d the source data array

public void copyFromUnchecked (int[] d)

Copy into this Allocation from an array. This method does not guarantee that the Allocation is compatible with the input buffer; it copies memory without reinterpretation.

Parameters
d the source data array

public void copyFromUnchecked (short[] d)

Copy into this Allocation from an array. This method does not guarantee that the Allocation is compatible with the input buffer; it copies memory without reinterpretation.

Parameters
d the source data array

public void copyFromUnchecked (byte[] d)

Copy into this Allocation from an array. This method does not guarantee that the Allocation is compatible with the input buffer; it copies memory without reinterpretation.

Parameters
d the source data array

public void copyFromUnchecked (float[] d)

Copy into this Allocation from an array. This method does not guarantee that the Allocation is compatible with the input buffer; it copies memory without reinterpretation.

Parameters
d the source data array

public void copyTo (byte[] d)

Copy from the Allocation into a byte array. The array must be at least as large as the Allocation. The allocation must be of an 8 bit integer Element type.

Parameters
d The array to be set from the Allocation.

public void copyTo (int[] d)

Copy from the Allocation into a int array. The array must be at least as large as the Allocation. The allocation must be of an 32 bit integer Element type.

Parameters
d The array to be set from the Allocation.

public void copyTo (float[] d)

Copy from the Allocation into a float array. The array must be at least as large as the Allocation. The allocation must be of an 32 bit float Element type.

Parameters
d The array to be set from the Allocation.

public void copyTo (short[] d)

Copy from the Allocation into a short array. The array must be at least as large as the Allocation. The allocation must be of an 16 bit integer Element type.

Parameters
d The array to be set from the Allocation.

public void copyTo ( Bitmap b)

Copy from the Allocation into a Bitmap . The bitmap must match the dimensions of the Allocation.

Parameters
b The bitmap to be set from the Allocation.

public static Allocation createCubemapFromBitmap ( RenderScript rs, Bitmap b)

Creates a non-mipmapped cubemap Allocation for use as a graphics texture from a Bitmap containing the horizontal list of cube faces. Each face must be a square, have the same size as all other faces, and have a width that is a power of 2.

Parameters
rs Context to which the allocation will belong.
b bitmap with cubemap faces layed out in the following format: right, left, top, bottom, front, back
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromBitmap ( RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)

Creates a cubemap Allocation from a Bitmap containing the horizontal list of cube faces. Each face must be a square, have the same size as all other faces, and have a width that is a power of 2.

Parameters
rs Context to which the allocation will belong.
b Bitmap with cubemap faces layed out in the following format: right, left, top, bottom, front, back
mips specifies desired mipmap behaviour for the cubemap
usage bit field specifying how the cubemap is utilized
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromCubeFaces ( RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg, Allocation.MipmapControl mips, int usage)

Creates a cubemap Allocation from 6 Bitmap objects containing the cube faces. Each face must be a square, have the same size as all other faces, and have a width that is a power of 2.

Parameters
rs Context to which the allocation will belong.
xpos cubemap face in the positive x direction
xneg cubemap face in the negative x direction
ypos cubemap face in the positive y direction
yneg cubemap face in the negative y direction
zpos cubemap face in the positive z direction
zneg cubemap face in the negative z direction
mips specifies desired mipmap behaviour for the cubemap
usage bit field specifying how the cubemap is utilized
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromCubeFaces ( RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg)

Creates a non-mipmapped cubemap Allocation for use as a sampler input from 6 Bitmap objects containing the cube faces. Each face must be a square, have the same size as all other faces, and have a width that is a power of 2.

Parameters
rs Context to which the allocation will belong.
xpos cubemap face in the positive x direction
xneg cubemap face in the negative x direction
ypos cubemap face in the positive y direction
yneg cubemap face in the negative y direction
zpos cubemap face in the positive z direction
zneg cubemap face in the negative z direction
Returns
  • allocation containing cubemap data

public static Allocation createFromBitmap ( RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)

Creates an Allocation from a Bitmap .

Parameters
rs Context to which the allocation will belong.
b Bitmap source for the allocation data
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the allocation is utilized
Returns
  • Allocation containing bitmap data

public static Allocation createFromBitmap ( RenderScript rs, Bitmap b)

Creates an Allocation from a Bitmap .

This Allocation will be created with USAGE_SHARED , and USAGE_SCRIPT .

Parameters
rs Context to which the allocation will belong.
b bitmap source for the allocation data
Returns
  • Allocation containing bitmap data

public static Allocation createFromBitmapResource ( RenderScript rs, Resources res, int id)

Creates a non-mipmapped Allocation to use as a graphics texture from the Bitmap referenced by resource ID.

This allocation will be created with USAGE_SCRIPT and USAGE_GRAPHICS_TEXTURE .

Parameters
rs Context to which the allocation will belong.
res application resources
id resource id to load the data from
Returns
  • Allocation containing resource data

public static Allocation createFromBitmapResource ( RenderScript rs, Resources res, int id, Allocation.MipmapControl mips, int usage)

Creates an Allocation from the Bitmap referenced by resource ID.

Parameters
rs Context to which the allocation will belong.
res application resources
id resource id to load the data from
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the allocation is utilized
Returns
  • Allocation containing resource data

public static Allocation createFromString ( RenderScript rs, String str, int usage)

Creates an Allocation containing string data encoded in UTF-8 format.

Parameters
rs Context to which the allocation will belong.
str string to create the allocation from
usage bit field specifying how the allocaiton is utilized

public static Allocation createSized ( RenderScript rs, Element e, int count, int usage)

Creates an Allocation with a specified number of given elements

Parameters
rs Context to which the Allocation will belong.
e Element to use in the Allocation
count the number of Elements in the Allocation
usage bit field specifying how the Allocation is utilized
Returns
  • allocation

public static Allocation createSized ( RenderScript rs, Element e, int count)

Creates an Allocation with a specified number of given elements

Parameters
rs Context to which the Allocation will belong.
e Element to use in the Allocation
count the number of Elements in the Allocation
Returns
  • allocation

public static Allocation createTyped ( RenderScript rs, Type type, int usage)

Creates an Allocation with the size specified by the type and no mipmaps generated by default

Parameters
rs Context to which the allocation will belong.
type renderscript type describing data layout
usage bit field specifying how the allocation is utilized
Returns
  • allocation

public static Allocation createTyped ( RenderScript rs, Type type)

Creates an Allocation for use by scripts with a given Type and no mipmaps

Parameters
rs Context to which the Allocation will belong.
type RenderScript Type describing data layout
Returns
  • allocation

public static Allocation createTyped ( RenderScript rs, Type type, Allocation.MipmapControl mips, int usage)

Creates a new Allocation with the given Type , mipmap flag, and usage flags.

Parameters
type RenderScript type describing data layout
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the Allocation is utilized

public void generateMipmaps ()

Generate a mipmap chain. This is only valid if the Type of the Allocation includes mipmaps.

This function will generate a complete set of mipmaps from the top level LOD and place them into the script memory space.

If the Allocation is also using other memory spaces, a call to syncAll(Allocation.USAGE_SCRIPT) is required.

public int getBytesSize ()

Get the size of the Allocation in bytes.

Returns
  • size of the Allocation in bytes.

public Element getElement ()

Get the Element of the Type of the Allocation.

Returns
  • Element

public Type getType ()

Get the Type of the Allocation.

Returns
  • Type

public int getUsage ()

Get the usage flags of the Allocation.

Returns
  • usage this Allocation's set of the USAGE_* flags OR'd together

public void ioReceive ()

Receive the latest input into the Allocation. This operation is only valid if USAGE_IO_INPUT is set on the Allocation.

public void ioSend ()

Send a buffer to the output stream. The contents of the Allocation will be undefined after this operation. This operation is only valid if USAGE_IO_OUTPUT is set on the Allocation.

public void setFromFieldPacker (int xoff, FieldPacker fp)

This is only intended to be used by auto-generated code reflected from the RenderScript script files and should not be used by developers.

public void setFromFieldPacker (int xoff, int component_number, FieldPacker fp)

This is only intended to be used by auto-generated code reflected from the RenderScript script files.

public void syncAll (int srcLocation)

Propagate changes from one usage of the Allocation to the other usages of the Allocation.

Protected Methods

protected void finalize ()

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable ), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.