org.hypergraphdb.cache

Class WeakRefAtomCache

java.lang.Object

org.hypergraphdb.cache.WeakRefAtomCache

All Implemented Interfaces:

HGAtomCache

public class WeakRefAtomCache
extends Object
implements HGAtomCache

This cache implementation interacts with the Java garbage collector, by using the java.lang.ref facilities, in order to implement its eviction policy. The eviction policy is the following: an atom is removed from the cache if and only if either (1) its runtime Java instance is garbage collected or (2) it is explicitly removed from the HyperGraph DB. Freezing an atom will keep it in the cache even when it's garbage collected, but not if it's removed from DB altogether.

For atom caching, two maps are maintained: handle->Java object and Java object->handle. The latter is an identity map, using the == operator and the System.identityHashCode instead of the regular Object equals and hashCode methods. This is because if an atom changes (e.g. some of its properties are modified), the results of equals and hashCode will most likely change as well and it will become impossible to recover the atom's handle. Unfortunately, a long standing bug in the JVM has System.identityHashCode highly inefficient.

Author:

Borislav Iordanov

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

Constructor Summary

Constructors

Constructor and Description
WeakRefAtomCache()

Method Summary

Methods

Modifier and Type	Method and Description
HGLiveHandle	atomAdded(HGPersistentHandle pHandle, Object atom, HGAtomAttrib attrib) Inform the cache that a new atom has just been added to the database.
HGLiveHandle	atomRead(HGPersistentHandle pHandle, Object atom, HGAtomAttrib attrib) Inform the cache that an atom has just been read from persistent storage.
HGLiveHandle	atomRefresh(HGLiveHandle handle, Object atom, boolean replace) Replace the runtime instance of an atom with a new value.
void	close() Close the cache.
void	freeze(HGLiveHandle handle) Freezing an atom in the cache would prevent it from ever being removed.
HGLiveHandle	get(HGPersistentHandle pHandle) Retrieve an atom from the cache by its persistent handle.
HGLiveHandle	get(Object atom) Retrieve the HGLiveHandle of a run-time atom instance.
HGCache<HGPersistentHandle,IncidenceSet>	getIncidenceCache() Return the incidence set cache.
boolean	isFrozen(HGLiveHandle handle) Find out whether a given atom is frozen in the cache.
void	printSizes()
void	remove(HGHandle handle) Force a removal a given atom from the cache.
void	setHyperGraph(HyperGraph graph) Set the HyperGraph within which this cache is operating.
void	setIncidenceCache(HGCache<HGPersistentHandle,IncidenceSet> cache) Set the implementation of the incidence sets cache to use.
void	unfreeze(HGLiveHandle handle) Unfreezing a previously frozen atom makes it available for eviction.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

public static final long DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

See Also:

Constant Field Values

Constructor Detail

WeakRefAtomCache

public WeakRefAtomCache()

Method Detail

setIncidenceCache

public void setIncidenceCache(HGCache<HGPersistentHandle,IncidenceSet> cache)

Description copied from interface: HGAtomCache

Set the implementation of the incidence sets cache to use.

Specified by:

setIncidenceCache in interface HGAtomCache

getIncidenceCache

public HGCache<HGPersistentHandle,IncidenceSet> getIncidenceCache()

Description copied from interface: HGAtomCache

Return the incidence set cache. The incidence set cache is maintained separately from the main atom cache. Incidence sets don't hold actual atoms, but only their handles. Also, they are ordered and can be queried for membership efficiently.

Specified by:

getIncidenceCache in interface HGAtomCache

setHyperGraph

public void setHyperGraph(HyperGraph graph)

Description copied from interface: HGAtomCache

Set the HyperGraph within which this cache is operating. A given cache implementation may or may not need a reference to the HyperGraph instance, depending on the level of sophistication of the cache. For example, some cache policies may want to persist certain usage statistics in the HGStore, others may want to attach particular importance to certain atom types etc.

Specified by:

setHyperGraph in interface HGAtomCache

Parameters:

graph - The HyperGraph instance.

atomAdded

public HGLiveHandle atomAdded(HGPersistentHandle pHandle,
                     Object atom,
                     HGAtomAttrib attrib)

Description copied from interface: HGAtomCache

Inform the cache that a new atom has just been added to the database. The cache is free to decide whether that atom should be actually cached or not, but in any case it must construct and return HGLiveHandle for the atom.

Specified by:

atomAdded in interface HGAtomCache

Parameters:

pHandle - The persistent handle of the atom.

atom - The run-time instance of the atom.

attrib - Atom management related attributes that must be stored as part of its live handle.

Returns:

A valid HGLiveHandle to the atom.

atomRead

public HGLiveHandle atomRead(HGPersistentHandle pHandle,
                    Object atom,
                    HGAtomAttrib attrib)

Description copied from interface: HGAtomCache

Inform the cache that an atom has just been read from persistent storage. The cache is free to decide whether that atom should be actually cached or not, but in any case it must construct and return HGLiveHandle for the atom.

If the atom corresponding to specified persistent handle is already in the cache, it should be replaced with the new passed in value.

Specified by:

atomRead in interface HGAtomCache

Parameters:

pHandle - The persistent handle of the atom.

atom - The run-time instance of the atom.

attrib - Atom management related attributes that must be stored as part of its live handle.

Returns:

A valid HGLiveHandle to the atom.

atomRefresh

public HGLiveHandle atomRefresh(HGLiveHandle handle,
                       Object atom,
                       boolean replace)

Description copied from interface: HGAtomCache

Replace the runtime instance of an atom with a new value. This method is invoked when HyperGraph needs to inform the cache about a change of the value of an atom. The cache must assign the new reference to the cached live handle and, as the case may be, reinsert the atom into its caching structures.

Note that there are two important cases of "refreshing" an atom in the cache - the atom being reloaded from permanent storage or when there is an actual value change. In the former case, a transaction abort does not need to roll back changes in the caching structures while in the latter it does! The two cases are distinguished by the third parameter of this method. ??? Note that the cache should perform a replace if handle.getRef() != null && handle.getRef() != atom because this signals that a new value must be stored. If the atom's value hasn't changed (i.e. if handle.getRef() == atom) then nothing is done.

Specified by:

atomRefresh in interface HGAtomCache

Parameters:

handle - The HGLiveHandle handle of the atom to be refreshed.

atom - The atom value. HyperGraph will obtain this value either from the cache, in case the atom has already been re-fetched from storage after the eviction event, or it will retrieve and create a new run-time instance.

replace - true if this is a new atom value (old must be restored if the transaction aborts) and false if this is simply a reload from permanent storage where the effects of that reload may (or may not, depending on the implementation) be reversed in case of a transaction abort.

Returns:

Possibly a new live handle instance or the handle parameter depending on the implementation. If a new instance is return, the reference of the old instance is cleared.

close

public void close()

Description copied from interface: HGAtomCache

Close the cache. This will clear the cache, completely and perform any cleaning operations such as unloading of atoms and the like.

Once the cache is closed, it cannot be used again.

This method is normally invoked by HyperGraph only. The method is not guaranteed to be thread-safe. It can rely on the fact that no other threads are accessing the cache while it is executing.

Specified by:

close in interface HGAtomCache

get

public HGLiveHandle get(HGPersistentHandle pHandle)

Description copied from interface: HGAtomCache

Retrieve an atom from the cache by its persistent handle.

Specified by:

get in interface HGAtomCache

Parameters:

pHandle - The HGPersistentHandle of the desired atom.

Returns:

The HGLiveHandle of the atom or null if the atom is not in the cache.

get

public HGLiveHandle get(Object atom)

Description copied from interface: HGAtomCache

Retrieve the HGLiveHandle of a run-time atom instance.

Specified by:

get in interface HGAtomCache

Parameters:

atom - The atom object.

Returns:

The HGLiveHandle of that atom or null if the atom is not in the cache.

remove

public void remove(HGHandle handle)

Description copied from interface: HGAtomCache

Force a removal a given atom from the cache. This method is generally invoked when the atom is actually deleted from the graph.

If the incidence set of this atom was loaded in the cache, it should be removed as well.

Specified by:

remove in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be removed. If the atom is currently not in the cache, nothing should be done.

isFrozen

public boolean isFrozen(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Find out whether a given atom is frozen in the cache.

Specified by:

isFrozen in interface HGAtomCache

Parameters:

handle - The live handle of the atom.

Returns:

true if the atom is frozen (i.e. would never be evicted from the cache) and false otherwise.

freeze

public void freeze(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Freezing an atom in the cache would prevent it from ever being removed.

Specified by:

freeze in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be frozen. The atom must already be in the cache.

unfreeze

public void unfreeze(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Unfreezing a previously frozen atom makes it available for eviction. It is ok to unfreeze an atom that has never been frozen.

Specified by:

unfreeze in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be unfrozen. The atom must be in the cache.

printSizes

public void printSizes()