target_explorer/plugins/org.eclipse.tcf.te.tcf.core/src/org/eclipse/tcf/te/tcf/core/concurrent/CallbackMonitor.java

/*******************************************************************************
 * Copyright (c) 2011, 2015 Wind River Systems, Inc. and others. All rights reserved.
 * This program and the accompanying materials are made available under the terms
 * of the Eclipse Public License v1.0 which accompanies this distribution, and is
 * available at http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 * Wind River Systems - initial API and implementation
 *******************************************************************************/
package org.eclipse.tcf.te.tcf.core.concurrent;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Timer;

import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.MultiStatus;
import org.eclipse.tcf.te.runtime.interfaces.callback.ICallback;
import org.eclipse.tcf.te.tcf.core.activator.CoreBundleActivator;
import org.eclipse.tcf.te.tcf.core.nls.Messages;

/**
 * A helper class used to synchronize multiple threads. It is used
 * to join multiple threads which collaborate to create the pre-condition
 * of the callback code.
 * <p>
 * A callback monitor maintains a map containing a set of locks.
 * The collaborating threads should unlock one of its own lock in
 * it and wake up the callback if all the locks in the map is opened.
 * <p>
 * The following is an example:
 * <pre>
 * class Thread1 extends Thread {
 * 		CallbackMonitor monitor;
 * 		public Thread1(CallbackMonitor monitor){
 * 			this.monitor = monitor;
 * 		}
 * 		public void run() {
 * 			// Do the work
 * 			...
 * 			// Unlock this thread.
 * 			monitor.unlock(this)
 * 		}
 * }
 * class Thread2 extends Thread {
 * 		CallbackMonitor monitor;
 * 		public Thread2(CallbackMonitor monitor){
 * 			this.monitor = monitor;
 * 		}
 * 		public void run() {
 * 			// Do the work
 * 			...
 * 			// Unlock this thread.
 * 			monitor.unlock(this)
 * 		}
 * }
 * ...
 * public void collaborate() {
 * 		Runnable callback = new Runnable() {
 * 			public void run() {
 * 				// Do something which must be done after all the threads end.
 * 				...
 * 			}
 * 		};
 * 		CallbackMonitor monitor = new CallbackMonitor(callback);
 * 		Thread1 thread1 = new Thread1(monitor);
 * 		Thread2 thread2 = new Thread2(monitor);
 * 		...
 * 		monitor.lock(thread1, thread2, ...);
 * 		thread1.start();
 * 		thread2.start();
 * 		...
 * }
 * </pre>
 * <p>
 * The above creates multiple threads which lock on the monitor and
 * invoke unlock when they end. The keys they used can be anything which
 * are unique among the threads. Once all threads end, the callback defined
 * in the method will be invoked and do the thing which requires to be done
 * after the end of these threads.
 * <p>
 * <b>Note:</b><em>The threads which require collaboration on the callback
 * monitor should be started only after all the locks corresponding to them
 * are added. </em>
 * <p>
 * For example, the above threads are started after the monitor locks all the threads:
 * <pre>
 * 		monitor.lock(thread1, thread2, ...);
 * 		thread1.start();
 * 		thread2.start();
 * 		...
 * </pre>
 */
public class CallbackMonitor {
	// The default timeout value is one minute.
	private static final long DEFAULT_TIMEOUT = 60 * 1000L;
	// The callback which is invoked after all the locks are unlocked.
	private ICallback callback;
	// The lock map containing the keys and the corresponding running results.
	private Map<Object, IStatus> locks;

	/**
	 * Create a callback monitor with the specified callback with a default timeout.
	 *
	 * @param callback The callback to be invoked after all the locks being unlocked.
	 */
	public CallbackMonitor(ICallback callback) {
		this(callback, DEFAULT_TIMEOUT);
	}

	/**
	 * Create a callback monitor with the specified callback with a timeout. If
	 * the timeout is zero, then it will block forever until all locks are released.
	 *
	 * @param callback The callback to be invoked after all the locks being unlocked.
	 * @param timeout The timeout value.
	 */
	public CallbackMonitor(ICallback callback, long timeout) {
		Assert.isNotNull(callback);
		this.callback = callback;
		this.locks = Collections.synchronizedMap(new HashMap<Object, IStatus>());
		if (timeout > 0) {
			new Timer().schedule(new MonitorTask(callback, timeout), timeout, timeout);
		}
	}

	/**
	 * Create a callback monitor with the specified callback and the keys with a default
	 * timeout.
	 *
	 * @param callback The callback to be invoked after all the locks being unlocked.
	 * @param keys The keys to lock and unlock the locks.
	 */
	public CallbackMonitor(ICallback callback, Object...keys) {
		this(callback, DEFAULT_TIMEOUT, keys);
	}

	/**
	 * Create a callback monitor with the specified callback and the keys and a timeout. If
	 * the timeout is zero, then it will block forever until all locks are released.
	 *
	 * @param callback The callback to be invoked after all the locks being unlocked.
	 * @param keys The keys to lock and unlock the locks.
	 * @param timeout The timeout value.
	 */
	public CallbackMonitor(ICallback callback, long timeout, Object... keys) {
		Assert.isNotNull(callback);
		this.callback = callback;
		this.locks = Collections.synchronizedMap(new HashMap<Object, IStatus>());
		lock(keys);
		if (timeout > 0) {
			new Timer().schedule(new MonitorTask(callback, timeout), timeout, timeout);
		}
	}

	/**
	 * Add multiple locks with the specified keys.
	 *
	 * @param keys The keys whose locks are added.
	 */
	public void lock(Object... keys) {
		for(Object key : keys) {
			Assert.isNotNull(key);
			this.locks.put(key, null);
		}
	}

	/**
	 * Add a lock with the specified key.
	 *
	 * @param key The key whose lock is added.
	 */
	public void lock(Object key) {
		Assert.isNotNull(key);
		this.locks.put(key, null);
	}

	/**
	 * Unlock the lock with the specified key and status
	 * check if all the locks have been unlocked. If all the
	 * locks have been unlocked, then invoke the callback.
	 *
	 * @param key The key to unlock its lock.
	 */
	public void unlock(Object key, IStatus status) {
		Assert.isNotNull(key);
		Assert.isNotNull(status);
		locks.put(key, status);
		IStatus current = getCurrentStatus();
		synchronized (callback) {
			if (current != null && !callback.isDone()) {
				callback.done(this, current);
			}
		}
	}

	/**
	 * Check if all the locks are unlocked and return a running status.
	 *
	 * @return a MultiStatus object describing running result or null if not completed yet.
	 */
	private synchronized IStatus getCurrentStatus() {
		List<IStatus> list = new ArrayList<IStatus>();
		synchronized (locks) {
			for (Entry<Object, IStatus> entry : locks.entrySet()) {
				IStatus status = entry.getValue();
				if (status == null) return null;
				list.add(status);
			}
		}
		IStatus[] children = list.toArray(new IStatus[list.size()]);
		return new MultiStatus(CoreBundleActivator.getUniqueIdentifier(), 0, children, Messages.CallbackMonitor_AllTasksFinished, null);
	}
}