tyrex.util
Class WeakList

java.lang.Object
  tyrex.util.WeakList

public class WeakList

extends java.lang.Object

List of weak references allows objects to be tracked and claimed by the garbage collector. This is a simple implementation based on an array and users WeakReference for its entries.

The base assumption about this list is that it holds objects used by the application that require extra processing. When the application releases object, we are no longer interested in processing it. This list has preference to not hold or return objects that have been garbage collected (even if not finalized yet).

There is no direct access to the list, the only way to retrieve entries is through list(). Since unreferenced entires may be removed at any time, implementing indexed access is a bit hard. Instead, list() produces an array that points to all the referenced elements, and that array can be accessed by index. For as long as this array is referenced, no entries will be claimed.

Certain optimization decisions have been made in this list based on its projected usage, in particular:

• The internal array is not created until the first entry is placed in it -- the assumption is that many lists will go empty for the duration of their life/
• The array is initialized with a place for INITIAL_SIZE entries whiche seems a good compromise.
• When entries are removed from the array, their location in the table is set to null and reused later on, the array is not compacted
• Unreferenced entries are discarded first, before performing any operation on the table.

This object is not thread-safe.

Version:

$Revision: 1.5 $ $Date: 2001/03/12 19:20:21 $

Author:

Assaf Arkin

Field Summary

static int

INITIAL_SIZE This is the initial size of the array.

Constructor Summary

WeakList()

Method Summary

void	add(java.lang.Object object) Adds a new object to the list.
void	clear() Clears the contents of this list.
boolean	contains(java.lang.Object object) Returns true if the element is contained in the list and has not been garbage collected yet.
java.lang.Object[]	list() Returns an array representing the contents of this list.
java.lang.Object[]	list(java.lang.Class type) Returns an array representing the contents of this list.
static void	main(java.lang.String[] args)
java.lang.Object	remove(java.lang.Object object) Removes an object from the list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INITIAL_SIZE

public static final int INITIAL_SIZE

This is the initial size of the array. When the first entry is added, the array is created to hold that many entries. The larger this number is, the more memory we waste but the less array resizing we need if usage does grow within these bounds. 2 looks like a reasonable compromise for most cases.

See Also:

Constant Field Values

Constructor Detail

WeakList

public WeakList()

Method Detail

add

public void add(java.lang.Object object)

Adds a new object to the list.

Parameters:

object - The object to add

remove

public java.lang.Object remove(java.lang.Object object)

Removes an object from the list. If the object was in the list, it is returned. Returns null if the object was not in the list.

Parameters:

object - The object to remove

Returns:

The removed object, null if the object was not there

clear

public void clear()

Clears the contents of this list.

contains

public boolean contains(java.lang.Object object)

Returns true if the element is contained in the list and has not been garbage collected yet.

Parameters:

object - The object to test

Returns:

True if the object is contained in the list

list

public java.lang.Object[] list()

Returns an array representing the contents of this list.

Only objects that are referenced will be returned in the array, and these objects will be referenced by the array and not discarded for as long as the returned array is referenced.

This is the only way to access the list by index and operate on it without safety checks.

The returned array is a sparse array, it may contain null entries for objects that no longer exist.

Returns:

An array representing the contents of the list

list

public java.lang.Object[] list(java.lang.Class type)

Returns an array representing the contents of this list.

Only objects that are referenced will be returned in the array, and these objects will be referenced by the array and not discarded for as long as the returned array is referenced.

This is the only way to access the list by index and operate on it without safety checks.

The returned array is a sparse array, it may contain null entries for objects that no longer exist.

Parameters:

type - The object type requested

Returns:

An array representing the contents of the list

main

public static void main(java.lang.String[] args)