/*
* The MIT License
*
* Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package hudson.util;
import hudson.model.Fingerprint;
import hudson.model.FingerprintMap;
import java.io.IOException;
import java.lang.ref.SoftReference;
import java.text.MessageFormat;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
/**
* Convenient base class for implementing data storage.
*
* <p>
* One typical pattern of data storage in Hudson is the one that {@link Fingerprint}
* uses, where each data is keyed by an unique key (MD5 sum), and that key is used
* to determine the file system location of the data.
*
* On memory, each data is represented by one object ({@link Fingerprint}), and
* write access to the same data is coordinated by using synchronization.
*
* <p>
* With such storage, care has to be taken to ensure that there's only one data
* object in memory for any given key. That means load and create operation
* needs to be synchronized. This class implements this logic in a fairly efficient
* way, and thus intends to help plugins that want to use such data storage.
*
* @since 1.87
* @author Kohsuke Kawaguchi
* @see FingerprintMap
*/
public abstract class KeyedDataStorage<T,P> {
/**
* The value is either {@code SoftReference<Fingerprint>} or {@link Loading}.
*
* If it's {@link SoftReference}, that represents the currently available value.
* If it's {@link Loading}, then that indicates the fingerprint is being loaded.
* The thread can wait on this object to be notified when the loading completes.
*/
private final ConcurrentHashMap<String,Object> core = new ConcurrentHashMap<String,Object>();
/**
* Used in {@link KeyedDataStorage#core} to indicate that the loading of a fingerprint
* is in progress, so that we can avoid creating two {@link Fingerprint}s for the same hash code,
* but do so without having a single lock.
*/
private static class Loading<T> {
private T value;
private boolean set;
public synchronized void set(T value) {
this.set = true;
this.value = value;
notifyAll();
}
/**
* Blocks until the value is {@link #set(Object)} by another thread
* and returns the value.
*/
public synchronized T get() {
try {
while(!set)
wait();
return value;
} catch (InterruptedException e) {
// assume the loading failed, but make sure we process interruption properly later
Thread.currentThread().interrupt();
return null;
}
}
}
/**
* Atomically gets the existing data object if any, or if it doesn't exist
* {@link #create(String,Object) create} it and return it.
*
* @return
* Never null.
* @param createParams
* Additional parameters needed to create a new data object. Can be null.
*/
public T getOrCreate(String key, P createParams) throws IOException {
return get(key,true,createParams);
}
/**
* Finds the data object that matches the given key if available, or null
* if not found.
*/
public T get(String key) throws IOException {
return get(key,false,null);
}
/**
* Implementation of get/getOrCreate.
*/
protected T get(String key, boolean createIfNotExist, P createParams) throws IOException {
while(true) {
totalQuery.incrementAndGet();
Object value = core.get(key);
if(value instanceof SoftReference) {
SoftReference<T> wfp = (SoftReference<T>) value;
T t = wfp.get();
if(t!=null) {
cacheHit.incrementAndGet();
return t; // found it
}
weakRefLost.incrementAndGet();
}
if(value instanceof Loading) {
// another thread is loading it. get the value from there.
T t = ((Loading<T>)value).get();
if(t!=null || !createIfNotExist)
return t; // found it (t!=null) or we are just 'get' (!createIfNotExist)
}
// the fingerprint doesn't seem to be loaded thus far, so let's load it now.
// the care needs to be taken that other threads might be trying to do the same.
Loading<T> l = new Loading<T>();
if(value==null ? core.putIfAbsent(key,l)!=null : !core.replace(key,value,l)) {
// the value has changed since then. another thread is attempting to do the same.
// go back to square 1 and try it again.
continue;
}
T t = null;
try {
t = load(key);
if(t==null && createIfNotExist) {
t = create(key,createParams); // create the new data
if(t==null)
throw new IllegalStateException(); // bug in the derived classes
}
} catch(IOException e) {
loadFailure.incrementAndGet();
throw e;
} finally {
// let other threads know that the value is available now.
// when the original thread failed to load, this should set it to null.
l.set(t);
}
// the map needs to be updated to reflect the result of loading
if(t!=null)
core.put(key,new SoftReference<T>(t));
else
core.remove(key);
return t;
}
}
/**
* Attempts to load an existing data object from disk.
*
* <p>
* {@link KeyedDataStorage} class serializes the requests so that
* no two threads call the {@link #load(String)} method with the
* same parameter concurrently. This ensures that there's only
* up to one data object for any key.
*
* @return
* null if no such data exists.
* @throws IOException
* if load operation fails. This exception will be
* propagated to the caller.
*/
protected abstract T load(String key) throws IOException;
/**
* Creates a new data object.
*
* <p>
* This method is called by {@link #getOrCreate(String,Object)}
* if the data that matches the specified key does not exist.
* <p>
* Because of concurrency, another thread might call {@link #get(String)}
* as soon as a new data object is created, so it's important that
* this method returns a properly initialized "valid" object.
*
* @return
* never null. If construction fails, abort with an exception.
* @throws IOException
* if the method fails to create a new data object, it can throw
* {@link IOException} (or any other exception) and that will be
* propagated to the caller.
*/
protected abstract T create(String key, P createParams) throws IOException;
public void resetPerformanceStats() {
totalQuery.set(0);
cacheHit.set(0);
weakRefLost.set(0);
loadFailure.set(0);
}
/**
* Gets the short summary of performance statistics.
*/
public String getPerformanceStats() {
int total = totalQuery.get();
int hit = cacheHit.get();
int weakRef = weakRefLost.get();
int failure = loadFailure.get();
int miss = total-hit-weakRef;
return MessageFormat.format("total={0} hit={1}% lostRef={2}% failure={3}% miss={4}%",
total,hit,weakRef,failure,miss);
}
/**
* Total number of queries into this storage.
*/
public final AtomicInteger totalQuery = new AtomicInteger();
/**
* Number of cache hits (of all the total queries.)
*/
public final AtomicInteger cacheHit = new AtomicInteger();
/**
* Among cache misses, number of times when we had {@link SoftReference}
* but lost its value due to GC.
*
* <tt>totalQuery-cacheHit-weakRefLost</tt> means cache miss.
*/
public final AtomicInteger weakRefLost = new AtomicInteger();
/**
* Number of failures in loading data.
*/
public final AtomicInteger loadFailure = new AtomicInteger();
}