org.mentaqueue.Queue Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of menta-queue Show documentation
A super fast inter-thread transfer queue.
There is a newer version: 1.3.1
/*
 * MentaQueue => http://mentaqueue.soliveirajr.com
 * Copyright (C) 2012  Sergio Oliveira Jr. ([email protected])
 *
 * 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.1 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package org.mentaqueue;

/**
 * A queue API that allows batching and pooling of objects.
 * 
 *  So to offer you first get a mutable object from the queue by calling nextToOffer(), alter the object and call offer().
 *  That allows the queue objects to be pooled, avoiding any garbage collection.
 *  
 *  And to poll you first call available() to know how many objects you can safely poll, call poll() in a loop and when done call done().
 *  That allows polling to be batched, so you pay a synchronization price only when you call available() and NOT when you call poll().
 * 
 * @author Sergio Oliveira Jr.
 *
 * @param 
 */
public interface Queue {

	/**
	 * Return the next pooled mutable object that can be used by the producer.
	 * 
	 * @return the next mutable object that can be used by the producer.
	 */
	public E nextToOffer();

	/**
	 * Offer an object to the queue. The object must have been previously obtained by calling nextToOffer().
	 * 
	 * @param e the object to be offered to the queue.
	 */
	public void offer(E e);

	/**
	 * Return the number of objects that can be safely polled from this queue. It can return zero.
	 * 
	 * @return number of objects that can be polled.
	 */
	public long available();

	/**
	 * Poll a object from the queue. You can only call this method after calling available() so you
	 * know what is the maximum times you can call it.
	 * 
	 * NOTE: You should NOT keep your own reference for this mutable object. Read what you need to get from it and release its reference.
	 * 
	 * @return an object from the queue.
	 */
	public E poll();

	/**
	 * Called to indicate that all polling have been done.
	 */
	public void done();
}