documentation/specification/using_queue.txt

Using the Queue class
=====================

Contents
--------
 - Getting
 - Definition of Terms
 - Features
 - Using
 - Points to remember
 - Future additions

tdb1, 02/01/2001


Getting
-------
The Queue class can be found in the i-scream CVS repository, 
under experimental/server/Queue. Only the Queue.java and 
InvalidQueueException.java files are needed for use, however 
the other files provide examples of use.


Definition of Terms
-------------------
In this document I will use the following terms to describe 
the various actors in the system.

  - Queue
    The single instance of the Queue class being used.
    
  - Producer
    Usually the single object generating information, 
    although there could, in theory, be more than one.
    
  - Consumer(s)
    An object requiring data from the Producer.
  
  - queue
    A queue within the Queue class.


Features
--------
The Queue class provides an extensive range of features, 
mostly geared towards the requirements for a queue in the
i-scream server. It is, however, a very general-purpose 
design and could be used in any system where the producer 
and consumer are seperate threads, and cannot necessarily be 
co-ordinated.

The basic list of features are as follows;

  - Support for a multi-threaded environment
    
    In a system where the consumer and producer objects are 
    seperate threads it can be hard to coordinate the adding 
    and removal of data items to a queue. It may not be 
    sufficient for the consumer to keep trying until data is 
    available.
    
    To solve this the Queue provides a get() method that 
    will block, if the queue is empty, until data is 
    available.
  
  - Support for multiple consumers
    
    This does away with the need to externally created 
    multiple instances of the Queue class, which in turn 
    means only one reference need be passed around. The 
    Queue class could be considered a singleton, although it 
    isn't coded as such.
    
    Internally this is done by holding multiple queues, 
    which are populated using a single add() method. From 
    the perspective of the producer this makes life much 
    easier. Each queue is independant so each consumer can 
    operate different speeds.
  
  - Support for dynamic creation/removal of queues
    
    This allows a consumer to request removal of a queue it 
    may be using. This helps to keep things tidy if a 
    consumer needs to be shut down - ie. the internal queue 
    will no longer be populated, and any remaining data will 
    be left for garbage collection.
    
    A queue will be automatically created upon calling the 
    getQueue() method, which again makes life easier for a 
    system where consumers may be coming and going.


Using
-----

nb. Each example line is followed by the relevant method 
    header from the Queue.java file.

Using the Queue itself is a relatively simple task. Firstly 
a Queue object needs to be constructed;

  Queue q = new Queue();
  
   public Queue()

Then, a producer can begin adding data to this queue with no 
hassle. This should be looped around as data is added.

  q.add(o);
  
   public void add(Object o)

Next, a consumer needs to request a queue.

  n = q.getQueue();
  
   public int getQueue()

Then the consumer can get data items from it's queue. This 
can be repeated in a loop, and the method will block if no 
data is available.

  Object o = q.get(n);
  
   public Object get(int queue) throws InvalidQueueException

When a consumer has finished with the queue it should 
request it's removal.

  q.removeQueue(n);

   public void removeQueue(int queue)

That's all there is to it. For a final touch, there is a 
status method that will return the state of each queue, and 
provide a counter of how many data items have been added. 
It's intended use was as follows;

  System.out.println(q.status());

   public String status()


Points to remember
------------------
It is very important that the following be remembered.

  - ALWAYS call the removeQueue() method when a consumer no 
    longer needs to make use of the queue - even for a short 
    period of time. This avoids a queue filling up with data 
    (sometimes rather rapidly) when it isn't being drained.
  
  - A consumer will need to call getQueue() to have a queue 
    created for itself. It will then need to pass the 
    returned integer to the get() method every time it 
    requires data.


Future additions
----------------
The following ideas have been considered, but not yet 
implemented.

  - Limiting the size of a queue. This does, however, bring 
    up problems of what should happen when the queue is 
    full.


About
-----

This document was written by Tim Bishop [tdb1@ukc.ac.uk] for 
use by the team working on a 3rd year Computer Science 
project called "i-scream". More details can be found on the 
project website;

http://www.i-scream.org.uk
Revision:	1.1
Committed:	Tue Jan 2 02:27:15 2001 UTC (23 years, 10 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Log Message:	A documented outlining design and use of the Queue class.
#	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 [tdb1@ukc.ac.uk] 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.uk