i-scream documentation viewer

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 [tdb@i-scream.org] 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

© 2000-2015 i-scream « » www.i-scream.org