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.
#	User	Rev	Content
1	tdb	1.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