org.chronos.common.autolock.AutoLockable Maven / Gradle / Ivy

Go to download
package org.chronos.common.autolock;

/**
 * A {@link AutoLockable} is any object that can be locked {@linkplain #lock() locked} or using the
 * try-with-resources pattern.
 *
 * 
 * See {@link #lock()} for example usages.
 *
 * @author [email protected] -- Initial Contribution and API
 *
 */
public interface AutoLockable {

	/**
	 * Declares that a thread is about to perform an exclusive task that can not run in parallel with other tasks.
	 *
	 * 

	 * All invocations of this method must adhere to the following usage pattern:
	 *
	 * 
	 * try (LockHolder lock = lockable.lock()) {
	 * 	// ... perform tasks ...
	 * }
	 * 
	 *
	 * This method ensures that exclusive operations are properly blocked when another operation is taking place.
	 *
	 * @return The object representing lock ownership. The lock ownership will be released once {@link AutoLock#close()}
	 *         is invoked, which is called automatically by the try-with-resources statement.
	 */
	public AutoLock lock();

}