--- a/Queue.st	Sun Nov 02 18:35:27 1997 +0100
+++ b/Queue.st	Sun Nov 02 18:51:14 1997 +0100
@@ -10,8 +10,6 @@
  hereby transferred.
 "
 
-'From Smalltalk/X, Version:3.2.1 on 18-oct-1997 at 4:24:40 pm'                  !
-
 Collection subclass:#Queue
 	instanceVariableNames:'contentsArray readPosition writePosition tally'
 	classVariableNames:''
@@ -38,7 +36,7 @@
 documentation
 "
     Queues provides a simple implementation of a queue, where
-    elements are enterred at one end and removed at the other.
+    elements are added at one end and removed at the other.
     Access protocol is somewhat like a streams protocol, i.e. access
     is by #nextPut: and #next.
     The queue is created with a size argument, defining how many elements
@@ -46,15 +44,81 @@
     and another element is to be added. Likewise, it will report an error
     if its empty and an element is to be removed.
 
-    It is not safe when two processes access Queues simultanously,
+    It is NOT safe when two processes access Queues simultanously,
     since accesses to the internals are not protected against process-switches.
-
-    See SharedQueue for a class which is safe with processes and blocks
+    See SharedQueue for a class which IS safe with processes and blocks
     on write when full or on read when empty.
 
+    [Implementation note:]
+        All of queues functionality is also provided by the OrderedCollection (OC)
+        class; OC could easily simulate a queue (using #addLast: / #removeFirst).
+        The reason for providing Queue is not any speed advantage (actually,
+        OC seems to be a tiny bit faster). 
+        The point is that an implementation of SharedQueue as a subclass of OC
+        would require that many OC methods had to be blocked and/or redefined in
+        such a subclass, to care for simultaneous access.
+        Since queue implements a much more lightweight protocol, 
+        the sharedQueue implementation is much cleaner when based on a more
+        lightweight Queue class.
+        
     [author:]
         Claus Gittinger
 "
+!
+
+examples
+"
+  adding at one end, removing at the other ...
+                                                        [exBegin]
+    |q element  |
+
+    q := Queue new:10.
+    1 to:5 do:[:i | 
+        Transcript showCR:('adding ' , i printString).
+        q nextPut:i
+    ].
+
+    [q notEmpty] whileTrue:[
+        element := q next.
+        Transcript showCR:('removed ' , element printString).
+    ].
+                                                        [exEnd]
+
+
+
+  timing; Queue vs. OrderedCollection
+                                                        [exBegin]
+    |q oc tQueue tOC  |
+
+    q := Queue new:100.
+    tQueue := Time millisecondsToRun:[
+        1000 timesRepeat:[
+            1 to:100 do:[:i | 
+                q nextPut:i
+            ].
+            [q isEmpty] whileFalse:[
+                q next
+            ].
+        ]
+    ].
+
+    oc := OrderedCollection new:100.
+    tOC := Time millisecondsToRun:[
+        1000 timesRepeat:[
+            1 to:100 do:[:i | 
+                oc addLast:i
+            ].
+            [oc isEmpty] whileFalse:[
+                oc removeFirst
+            ].
+        ]
+    ].
+    Transcript showCR:('queue time: ' , tQueue printString , ' ms').
+    Transcript showCR:('oc time   : ' , tOC printString , ' ms').
+                                                        [exEnd]
+
+
+"
 ! !
 
 !Queue class methodsFor:'instance creation'!
@@ -231,5 +295,5 @@
 !Queue class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic2/Queue.st,v 1.19 1997-10-21 17:37:35 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/Queue.st,v 1.20 1997-11-02 17:51:14 cg Exp $'
 ! !