ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/using_queue.txt
Revision: 1.2
Committed: Sun Aug 1 10:39:55 2004 UTC (19 years, 8 months ago) by tdb
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +2 -2 lines
Log Message:
Catch a lot of old URL's and update them. Also remove a couple of old files
that aren't used.

File Contents

# Content
1 Using the Queue class
2 =====================
3
4 Contents
5 --------
6 - Getting
7 - Definition of Terms
8 - Features
9 - Using
10 - Points to remember
11 - Future additions
12
13 tdb1, 02/01/2001
14
15
16 Getting
17 -------
18 The Queue class can be found in the i-scream CVS repository,
19 under experimental/server/Queue. Only the Queue.java and
20 InvalidQueueException.java files are needed for use, however
21 the other files provide examples of use.
22
23
24 Definition of Terms
25 -------------------
26 In this document I will use the following terms to describe
27 the various actors in the system.
28
29 - Queue
30 The single instance of the Queue class being used.
31
32 - Producer
33 Usually the single object generating information,
34 although there could, in theory, be more than one.
35
36 - Consumer(s)
37 An object requiring data from the Producer.
38
39 - queue
40 A queue within the Queue class.
41
42
43 Features
44 --------
45 The Queue class provides an extensive range of features,
46 mostly geared towards the requirements for a queue in the
47 i-scream server. It is, however, a very general-purpose
48 design and could be used in any system where the producer
49 and consumer are seperate threads, and cannot necessarily be
50 co-ordinated.
51
52 The basic list of features are as follows;
53
54 - Support for a multi-threaded environment
55
56 In a system where the consumer and producer objects are
57 seperate threads it can be hard to coordinate the adding
58 and removal of data items to a queue. It may not be
59 sufficient for the consumer to keep trying until data is
60 available.
61
62 To solve this the Queue provides a get() method that
63 will block, if the queue is empty, until data is
64 available.
65
66 - Support for multiple consumers
67
68 This does away with the need to externally created
69 multiple instances of the Queue class, which in turn
70 means only one reference need be passed around. The
71 Queue class could be considered a singleton, although it
72 isn't coded as such.
73
74 Internally this is done by holding multiple queues,
75 which are populated using a single add() method. From
76 the perspective of the producer this makes life much
77 easier. Each queue is independant so each consumer can
78 operate different speeds.
79
80 - Support for dynamic creation/removal of queues
81
82 This allows a consumer to request removal of a queue it
83 may be using. This helps to keep things tidy if a
84 consumer needs to be shut down - ie. the internal queue
85 will no longer be populated, and any remaining data will
86 be left for garbage collection.
87
88 A queue will be automatically created upon calling the
89 getQueue() method, which again makes life easier for a
90 system where consumers may be coming and going.
91
92
93 Using
94 -----
95
96 nb. Each example line is followed by the relevant method
97 header from the Queue.java file.
98
99 Using the Queue itself is a relatively simple task. Firstly
100 a Queue object needs to be constructed;
101
102 Queue q = new Queue();
103
104 public Queue()
105
106 Then, a producer can begin adding data to this queue with no
107 hassle. This should be looped around as data is added.
108
109 q.add(o);
110
111 public void add(Object o)
112
113 Next, a consumer needs to request a queue.
114
115 n = q.getQueue();
116
117 public int getQueue()
118
119 Then the consumer can get data items from it's queue. This
120 can be repeated in a loop, and the method will block if no
121 data is available.
122
123 Object o = q.get(n);
124
125 public Object get(int queue) throws InvalidQueueException
126
127 When a consumer has finished with the queue it should
128 request it's removal.
129
130 q.removeQueue(n);
131
132 public void removeQueue(int queue)
133
134 That's all there is to it. For a final touch, there is a
135 status method that will return the state of each queue, and
136 provide a counter of how many data items have been added.
137 It's intended use was as follows;
138
139 System.out.println(q.status());
140
141 public String status()
142
143
144 Points to remember
145 ------------------
146 It is very important that the following be remembered.
147
148 - ALWAYS call the removeQueue() method when a consumer no
149 longer needs to make use of the queue - even for a short
150 period of time. This avoids a queue filling up with data
151 (sometimes rather rapidly) when it isn't being drained.
152
153 - A consumer will need to call getQueue() to have a queue
154 created for itself. It will then need to pass the
155 returned integer to the get() method every time it
156 requires data.
157
158
159 Future additions
160 ----------------
161 The following ideas have been considered, but not yet
162 implemented.
163
164 - Limiting the size of a queue. This does, however, bring
165 up problems of what should happen when the queue is
166 full.
167
168
169 About
170 -----
171
172 This document was written by Tim Bishop [tdb@i-scream.org] for
173 use by the team working on a 3rd year Computer Science
174 project called "i-scream". More details can be found on the
175 project website;
176
177 http://www.i-scream.org