casacore
Queue.h
Go to the documentation of this file.
1 //# Queue.h: A First-In-First-Out (FIFO) data structure.
2 //# Copyright (C) 1995,1999
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_QUEUE_H
29 #define CASA_QUEUE_H
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/Containers/Block.h>
33 
34 namespace casacore { //# NAMESPACE CASACORE - BEGIN
35 
36 //
37 
38 // <summary>
39 // A First-In-First-Out (FIFO) data structure.
40 // </summary>
41 //
42 // <reviewed reviewer="Gareth Hunt" date="94Jan06" tests="tQueue" demos="">
43 // </reviewed>
44 //
45 // <synopsis>
46 // A Queue as implemented here is a simple container which can grow with time,
47 // and which returns its elements (only) in the order they are inserted. That
48 // is, the fundamental operations are to insert an element in the queue (at the
49 // "back") and retrieve an element (from the "front").
50 //
51 // <srcblock>
52 // Queue<Int> queue;
53 // Int x;
54 // queue(1); // enqueue
55 // queue.enqueue(2); // enqueue
56 // queue(3); // enqueue
57 // queue(4); // enqueue
58 // queue.dequeue(x); // dequeue
59 // cout << x << endl;
60 // ...
61 // while (queue.nelements() > 0)
62 // cout << queue() << " "; // dequeue
63 // cout << endl;
64 // </srcblock>
65 //
66 // Presently the implementation is rather simple. It stores the elements in
67 // a Block<T> which resizes (exponentially to avoid quadratic behaviour) when
68 // necessary. New elements are added to the end of the block, old elements are
69 // pulled off the front of the Block. The positions at the beginning are only
70 // reclaimed when the queue is empty or the compress() member is called.
71 // This implementation is reasonably time
72 // efficient, but not necessarily space efficient. A more sophisticated
73 // implementation may be necessary eventually.
74 //
75 // To be used in a Queue, a class must have a default constructor, assignment
76 // operator, and copy constructor.
77 // </synopsis>
78 //
79 // <motivation>
80 // This class was written for an application which thought it needed to queue
81 // up some Glish events while it processed other Glish events. In fact that
82 // application (Clean) was simplified so that it doesn't presently operate that
83 // way.
84 // </motivation>
85 //
86 // <todo asof="28OCT94">
87 // <li> It is conceivable that an iterator might be useful for this class.
88 // <li> If this class is ever heavily used, a more space efficient
89 // implementation may be necessary.
90 // </todo>
91 
92 template<class T> class Queue
93 {
94 public:
95  // Create a Queue with no elements.
96  Queue();
97 
98  // Create a queue which is a copy of other. Compresses unused heap storage.
99  Queue(const Queue<T> &other);
100 
101  ~Queue();
102 
103  // Create a queue which is a copy of other. Compresses unused heap storage.
104  Queue<T> &operator=(const Queue<T> &other);
105 
106  // Place an element in the queue. After calling this,
107  // nelements() is increaed by one.
108  // <group>
109  void enqueue(const T &value);
110  // Short-hand for enqueue();
111  void operator()(const T &value);
112  // </group>
113 
114  // Remove an element from the head of the queue and decrease
115  // nelements() by one. If called when nelements() is zero, an
116  // exception is thrown.
117  // <group>
118  void dequeue(T &value);
119  // Short-hand for dequeue.
120  T operator()();
121  // </group>
122 
123  // Delete all the elements from the queue, and free up any resources.
124  void clear();
125 
126  // Leave this queue logically unchanged, but remove unused storage.
127  // With the present Block<T> based implementation, removes
128  // the unused entries at the beginning of the block.
129  void compress();
130 
131  // How many elements are in the queue?
132  uInt nelements() const {return next_p - first_p;}
133 private:
137 };
138 
139 
140 } //# NAMESPACE CASACORE - END
141 
142 #ifndef CASACORE_NO_AUTO_TEMPLATES
143 #include <casacore/casa/Containers/Queue.tcc>
144 #endif //# CASACORE_NO_AUTO_TEMPLATES
145 #endif
int Int
Definition: aipstype.h:47
void dequeue(T &value)
Remove an element from the head of the queue and decrease nelements() by one.
void enqueue(const T &value)
Place an element in the queue.
uInt nelements() const
How many elements are in the queue?
Definition: Queue.h:132
T operator()()
Short-hand for dequeue.
void compress()
Leave this queue logically unchanged, but remove unused storage.
void clear()
Delete all the elements from the queue, and free up any resources.
Block< T > data_p
Definition: Queue.h:136
A First-In-First-Out (FIFO) data structure.
Definition: Queue.h:92
simple 1-D array
Definition: ArrayIO.h:47
Queue()
Create a Queue with no elements.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
Queue< T > & operator=(const Queue< T > &other)
Create a queue which is a copy of other.
unsigned int uInt
Definition: aipstype.h:48