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 {@link UNBOUNDED_CAPACITY}.
  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         /**
  49          * The unbounded capacity value.
  50          */
  51         public static const int UNBOUNDED_CAPACITY = -1;
  52
  53         /**
  54          * The capacity of this queue (or null if capacity is not bound).
  55          */
  56         public abstract int capacity { get; }
  57
  58         /**
  59          * The remaining capacity of this queue (or null if capacity is not bound).
  60          */
  61         public abstract int remaining_capacity { get; }
  62
  63         /**
  64          * Specifies whether this queue is full.
  65          */
  66         public abstract bool is_full { get; }
  67
  68         /**
  69          * Offers the specified element to this queue.
  70          *
  71          * @param element the element to offer to the queue
  72          *
  73          * @return        true if the element was added to the queue
  74          */
  75         public abstract bool offer (G element);
  76
  77         /**
  78          * Peeks (retrieves, but not remove) an element from this queue.
  79          *
  80          * @return the element peeked from the queue (or null if none was available)
  81          */
  82         public abstract G? peek ();
  83
  84         /**
  85          * Polls (retrieves and remove) an element from this queue.
  86          *
  87          * @return the element polled from the queue (or null if none was available)
  88          */
  89         public abstract G? poll ();
  90
  91         /**
  92          * Drains the specified amount of elements from this queue in the specified
  93          * recipient collection.
  94          *
  95          * @param recipient the recipient collection to drain the elements to
  96          * @param amount    the amount of elements to drain
  97          *
  98          * @return          the amount of elements that were actually drained
  99          */
 100         public abstract int drain (Collection<G> recipient, int amount = -1);
 101 }