gee/queue.vala

   1 /* queue.vala
   2  *
   3  * Copyright (C) 2009  Didier Villevalois
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18  *
  19  * Author:
  20  *      Didier 'Ptitjes Villevalois <ptitjes@free.fr>
  21  */
  22
  23 /**
  24  * A collection designed for holding elements prior to processing.
  25  *
  26  * Although all Queue implementations do not limit the amount of elements they
  27  * can contain, this interface supports for capacity-bounded queues. When
  28  * capacity is not bound, then the {@link capacity} and
  29  * {@link remaining_capacity} both return null.
  30  *
  31  * This interface defines methods that will never fail whatever the state of
  32  * the queue is. For capacity-bounded queues, those methods will either return
  33  * false or null to specify that the insert or retrieval did not occur because
  34  * the queue was full or empty.
  35  *
  36  * Queue implementations are not limited to First-In-First-Out behavior and can
  37  * propose different ordering of their elements. Each Queue implementation have
  38  * to specify how it orders its elements.
  39  *
  40  * Queue implementations do not allow insertion of null elements, although some
  41  * implementations, such as {@link LinkedList}, do not prohibit insertion of
  42  * null. Even in the implementations that permit it, null should not be
  43  * inserted into a Queue, as null is also used as a special return value by the
  44  * poll method to indicate that the queue contains no elements.
  45  */
  46 public interface Gee.Queue<G> : Collection<G> {
  47         /**
  48          * The capacity of this queue (or null if capacity is not bound).
  49          */
  50         public abstract int? capacity { get; }
  51
  52         /**
  53          * The remaining capacity of this queue (or null if capacity is not bound).
  54          */
  55         public abstract int? remaining_capacity { get; }
  56
  57         /**
  58          * Specifies whether this queue is full.
  59          */
  60         public abstract bool is_full { get; }
  61
  62         /**
  63          * Offers the specified element to this queue.
  64          *
  65          * @param element the element to offer to the queue
  66          *
  67          * @return        true if the element was added to the queue
  68          */
  69         public abstract bool offer (G element);
  70
  71         /**
  72          * Peeks (retrieves, but not remove) an element from this queue.
  73          *
  74          * @return the element peeked from the queue (or null if none was available)
  75          */
  76         public abstract G? peek ();
  77
  78         /**
  79          * Polls (retrieves and remove) an element from this queue.
  80          *
  81          * @return the element polled from the queue (or null if none was available)
  82          */
  83         public abstract G? poll ();
  84
  85         /**
  86          * Drains the specified amount of elements from this queue in the specified
  87          * recipient collection.
  88          *
  89          * @param recipient the recipient collection to drain the elements to
  90          * @param amount    the amount of elements to drain
  91          *
  92          * @return          the amount of elements that were actually drained
  93          */
  94         public abstract int drain (Collection<G> recipient, int amount = -1);
  95 }