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

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

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

	/**
	 * 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.lockExclusive()) {
	 * 	// ... 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 lockExclusive();

	/**
	 * Declares that a thread is about to perform a non-exclusive task that can run in parallel with other non-exclusive
	 * locking tasks.
	 *
	 * 
	 * All invocations of this method must adhere to the following usage pattern:
	 *
	 * 
	 * try (LockHolder lock = lockable.lockNonExclusive()) {
	 * 	// ... perform tasks ...
	 * }
	 * 
	 *
	 * This method ensures that non-exclusive operations are properly blocked when an exclusive 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 lockNonExclusive();

}