Add documentation.

p4raw-id: //depot/perl@16451

diff --git a/ext/threads/shared/queue.pm b/ext/threads/shared/queue.pm
index e849c62..542c000 100644 (file)
--- a/ext/threads/shared/queue.pm
+++ b/ext/threads/shared/queue.pm
@@ -44,3 +44,63 @@ sub pending  {
 
 1;
 
+=head1 NAME
+
+threads::shared::queue - thread-safe queues
+
+=head1 SYNOPSIS
+
+    use threads::shared::queue;
+    my $q = new threads::shared::queue;
+    $q->enqueue("foo", "bar");
+    my $foo = $q->dequeue;    # The "bar" is still in the queue.
+    my $foo = $q->dequeue_nb; # returns "bar", or undef if the queue was
+                              # empty
+    my $left = $q->pending;   # returns the number of items still in the queue
+
+=head1 DESCRIPTION
+
+A queue, as implemented by C<threads::shared::queue> is a thread-safe 
+data structure much like a list.  Any number of threads can safely 
+add elements to the end of the list, or remove elements from the head 
+of the list. (Queues don't permit adding or removing elements from 
+the middle of the list)
+
+=head1 FUNCTIONS AND METHODS
+
+=over 8
+
+=item new
+
+The C<new> function creates a new empty queue.
+
+=item enqueue LIST
+
+The C<enqueue> method adds a list of scalars on to the end of the queue.
+The queue will grow as needed to accomodate the list.
+
+=item dequeue
+
+The C<dequeue> method removes a scalar from the head of the queue and
+returns it. If the queue is currently empty, C<dequeue> will block the
+thread until another thread C<enqueue>s a scalar.
+
+=item dequeue_nb
+
+The C<dequeue_nb> method, like the C<dequeue> method, removes a scalar from
+the head of the queue and returns it. Unlike C<dequeue>, though,
+C<dequeue_nb> won't block if the queue is empty, instead returning
+C<undef>.
+
+=item pending
+
+The C<pending> method returns the number of items still in the queue.
+
+=back
+
+=head1 SEE ALSO
+
+L<threads> L<threads::shared>
+
+=cut
+