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
  34  * because 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
  41  * some implementations, such as {@link LinkedList}, do not prohibit insertion
  42  * of ``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
  44  * the 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
  60          * bound).
  61          */
  62         public abstract int remaining_capacity { get; }
  63
  64         /**
  65          * Specifies whether this queue is full.
  66          */
  67         public abstract bool is_full { get; }
  68
  69         /**
  70          * Offers the specified element to this queue.
  71          *
  72          * @param element the element to offer to the queue
  73          *
  74          * @return        ``true`` if the element was added to the queue
  75          */
  76         public abstract bool offer (G element);
  77
  78         /**
  79          * Peeks (retrieves, but not remove) an element from this queue.
  80          *
  81          * @return the element peeked from the queue (or ``null`` if none was
  82          *         available)
  83          */
  84         public abstract G? peek ();
  85
  86         /**
  87          * Polls (retrieves and remove) an element from this queue.
  88          *
  89          * @return the element polled from the queue (or ``null`` if none was
  90          *         available)
  91          */
  92         public abstract G? poll ();
  93
  94         /**
  95          * Drains the specified amount of elements from this queue in the specified
  96          * recipient collection.
  97          *
  98          * @param recipient the recipient collection to drain the elements to
  99          * @param amount    the amount of elements to drain
 100          *
 101          * @return          the amount of elements that were actually drained
 102          */
 103         public abstract int drain (Collection<G> recipient, int amount = -1);
 104 }