org.hypergraphdb.cache

Class DefaultAtomCache

java.lang.Object

org.hypergraphdb.cache.DefaultAtomCache

All Implemented Interfaces:

HGAtomCache

public final class DefaultAtomCache
extends Object
implements HGAtomCache

A default, simple implementation of a run-time cache of hypergraph atoms.

IMPLEMENTATION NOTE: This implementation maintains usage statistics (access count and last time of access), calculates an importance function based on those statistics and maintains a priority queue based on that importance. This incurs a significant memory overhead on a per atom basis. But the importance-based eviction policy is quite accurate. This implementation makes more sense when atoms are relatively large, but we need to come up and experiment with other schemas for cache maintenance. Something based on Java weak reference might work well, for example.

TODO: this implementation is NOT thread-safe. Mutexes need to be inserted at various cache manipulation points.

Author:

Borislav Iordanov

Constructor Summary

Constructors

Constructor and Description
DefaultAtomCache()

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) Associate an atom instance and a persistent handle with a live handle.
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) Lookup in the cache for a live handle corresponding to a persistent handle.
HGLiveHandle	get(Object atom) Retrieve the live handle of an atom instance.
HGCache<HGPersistentHandle,IncidenceSet>	getIncidenceCache() Return the incidence set cache.
long	getMaxAtoms()
long	getMaxIncidenceSets()
double	importanceOf(org.hypergraphdb.cache.DefaultAtomCache.LiveHandle cached)
boolean	isFrozen(HGLiveHandle handle) Find out whether a given atom is frozen in the cache.
void	remove(HGHandle handle) Remove a live handle and all its associations from the cache.
void	setHyperGraph(HyperGraph hg) 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	setMaxAtoms(long maxAtoms)
void	setMaxIncidenceSets(long maxIncidenceSets)
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

Constructor Detail

DefaultAtomCache

public DefaultAtomCache()

Method Detail

importanceOf

public double importanceOf(org.hypergraphdb.cache.DefaultAtomCache.LiveHandle cached)

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

setMaxAtoms

public void setMaxAtoms(long maxAtoms)

getMaxAtoms

public long getMaxAtoms()

setMaxIncidenceSets

public void setMaxIncidenceSets(long maxIncidenceSets)

getMaxIncidenceSets

public long getMaxIncidenceSets()

setHyperGraph

public void setHyperGraph(HyperGraph hg)

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:

hg - The HyperGraph instance.

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)

Lookup in the cache for a live handle corresponding to a 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)

Retrieve the live handle of an 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.

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)

Associate an atom instance and a persistent handle with a live handle.

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.

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.

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.

remove

public void remove(HGHandle handle)

Remove a live handle and all its associations from the cache.

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.