org.hypergraphdb.cache
Class DefaultAtomCache

java.lang.Object
  org.hypergraphdb.cache.DefaultAtomCache

All Implemented Interfaces:

HGAtomCache

public final class DefaultAtomCache
extends java.lang.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 a relatively large, but we need to come up and experiment with other schemas for cache maintanance. 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

Nested Class Summary

class

DefaultAtomCache.IncidenceDetachAction

Constructor Summary

DefaultAtomCache()

Method Summary

HGLiveHandle	atomRead(HGPersistentHandle pHandle, java.lang.Object atom, byte flags) Associate an atom instance and a persistent handle with a live handle.
HGManagedLiveHandle	atomRead(HGPersistentHandle pHandle, java.lang.Object atom, byte flags, long retrievalCount, long lastAccessTime) Inform the cache that an atom with system-level attributes has been loaded.
void	atomRefresh(HGLiveHandle handle, java.lang.Object atom) Refresh a previously evicted atom.
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(java.lang.Object atom) Retrieve the live handle of an atom instance.
HGHandle[]	getIncidenceSet(HGPersistentHandle handle) Return the incidence set of a given atom or null if the set is not in the cache.
long	getMaxAtoms()
long	getMaxIncidenceSets()
double	importanceOf(org.hypergraphdb.cache.DefaultAtomCache.LiveHandle cached)
void	incidenceSetRead(HGPersistentHandle handle, HGHandle[] incidenceSet) Inform the cache that the incidence set of a given atom has been retrieved from permanent storage.
boolean	isFrozen(HGLiveHandle handle) Find out whether a given atom is frozen in the cache.
void	remove(HGLiveHandle handle) Remove a live handle and all its associations from the cache.
void	removeIncidenceSet(HGPersistentHandle handle) Remove the incidence set of an atom from the cache.
void	setHyperGraph(HyperGraph hg) Set the HyperGraph within which this cache is operating.
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

equals, 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)

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 guarantueed 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(java.lang.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.

atomRead

public HGLiveHandle atomRead(HGPersistentHandle pHandle,
                             java.lang.Object atom,
                             byte flags)

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.

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

Returns:

A valid HGLiveHandle to the atom.

atomRead

public HGManagedLiveHandle atomRead(HGPersistentHandle pHandle,
                                    java.lang.Object atom,
                                    byte flags,
                                    long retrievalCount,
                                    long lastAccessTime)

Description copied from interface: HGAtomCache

Inform the cache that an atom with system-level attributes has been loaded. This has the same function as the simpler version of atomRead, but the cache must construct an instance of HGExtLiveHandle for purposes of non-default atom management.

Specified by:

atomRead in interface HGAtomCache

Parameters:

pHandle - The persistent handle of the atom.

atom - The run-time instance of the atom.

flags - The system flags for this atom.

retrievalCount - The recorded overall retrieval count for this atom.

lastAccessTime - A timestamps (in milliseconds) representing the last time this atom was accessed.

Returns:

A HGManagedLiveHandle encapsulating the atom instance, persistence handle and system-level attributes.

atomRefresh

public void atomRefresh(HGLiveHandle handle,
                        java.lang.Object atom)

Description copied from interface: HGAtomCache

Refresh a previously evicted atom. 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.

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 refetched from storage after the eviction event, or it will retrieve and create a new run-time instance.

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.

incidenceSetRead

public void incidenceSetRead(HGPersistentHandle handle,
                             HGHandle[] incidenceSet)

Description copied from interface: HGAtomCache

Inform the cache that the incidence set of a given atom has been retrieved from permanent storage.

The cache may decide to cache the incidence set or not. HyperGraph will usually query the cache for the incidence set of an atom before reading from storage.

IMPLEMENTATION NOTE: the current/default storage mechanism for HyperGraphDB being BerkeleyDB, there is relatively little need to cache a lot of incidence sets. Usually BerkeleyDB has its own cache and since construction of a HGHandle from byte[] is quite fast (compared to atom instance construction) one can rely mostly on the underlying Berkeley DB's cache for incidence set. [note on the note: this is pure speculation, never measured any of this. ;)].

Specified by:

incidenceSetRead in interface HGAtomCache

Parameters:

handle - The HGPersistentHandle of the atom whose incidence set has been retrieved.

incidenceSet - The incidence set of the atom.

getIncidenceSet

public HGHandle[] getIncidenceSet(HGPersistentHandle handle)

Description copied from interface: HGAtomCache

Return the incidence set of a given atom or null if the set is not in the cache.

Specified by:

getIncidenceSet in interface HGAtomCache

Parameters:

handle - The persistent handle of the atom whose incidence set is desired.

Returns:

A HGHandle array holding the handle of all links pointing to the given atom.

removeIncidenceSet

public void removeIncidenceSet(HGPersistentHandle handle)

Description copied from interface: HGAtomCache

Remove the incidence set of an atom from the cache.

Specified by:

removeIncidenceSet in interface HGAtomCache

Parameters:

handle - The HGPersistentHandle of the atom whose incidence set is to be removed.

remove

public void remove(HGLiveHandle 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.