org.objectweb.dream.synchro.SemaphoreItf Maven / Gradle / Ivy
/**
* Dream
* Copyright (C) 2003-2004 INRIA Rhone-Alpes
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Contact : [email protected]
*
* Initial developer(s): Vivien Quema
* Contributor(s):
*/
package org.objectweb.dream.synchro;
import org.objectweb.fractal.fraclet.annotation.annotations.Interface;
/**
* A counting semaphore component maintains a set of permits. Each acquire()
* blocks if necessary until a permit is available, and then takes it. Each
* release adds a permit. A semaphore initialized to 1 can serve as a mutual
* exclusion lock.
*
* Different implementations of this interface may provide different ordering
* guarantees (or lack thereof) surrounding which threads will be resumed upon a
* signal.
*
* Note: Inspired by Doug Lea's SemaphoreItf class.
*/
@Interface(name = SemaphoreItf.ITF_NAME)
public interface SemaphoreItf
{
/** The default name of the {@link SemaphoreItf }interface. */
String ITF_NAME = "semaphore";
/**
* Waits until a permit is available, and take one
*
* @throws InterruptedException if the thread is interrupted while trying to
* acquire the permit.
*/
void acquire() throws InterruptedException;
/**
* Waits at most msecs millisconds for a permit.
*
* @param msecs the number of milleseconds to wait. An argument less than or
* equal to zero means not to wait at all. However, this may still
* require access to a synchronization lock, which can impose
* unbounded delay if there is a lot of contention among threads.
* @return true if acquired.
* @throws InterruptedException if the thread is interrupted while waiting for
* the permit.
*/
boolean attempt(long msecs) throws InterruptedException;
/**
* Returns the current number of available permits.
*
* @return an accurate, but possibly unstable value, that may change
* immediately after returning.
*/
long permits();
/**
* Release a permit
*/
void release();
/**
* Releases N permits.
*
* @param n the number of permits to be released.
* @throws IllegalArgumentException if n is negative.
*/
void release(long n) throws IllegalArgumentException;
}