From: mike <mike>
Date: Tue, 13 Dec 2005 16:22:41 +0000 (+0000)
Subject: Add descriptions of ZOOM::event() and ZOOM::Connection::last_event(),
X-Git-Tag: cpan_1_22~320
X-Git-Url: http://sru.miketaylor.org.uk/?a=commitdiff_plain;h=202fa72d1f5647efa7299a32df31de8f64bf7733;p=ZOOM-Perl-moved-to-github.git

Add descriptions of ZOOM::event() and ZOOM::Connection::last_event(),
even though they are respectively unimplemented and untested.
---

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index ebd3c55..20694d4 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.20 2005-12-13 16:03:14 mike Exp $
+# $Id: ZOOM.pod,v 1.21 2005-12-13 16:22:41 mike Exp $
 
 use strict;
 use warnings;
@@ -38,8 +38,8 @@ API such as ZOOM is that all implementations should be compatible
 anyway; but knowing that the same code is running is reassuring.)
 
 The ZOOM module provides two enumerations (C<ZOOM::Error> and
-C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
-package itself, and eight classes:
+C<ZOOM::Event>), two utility functions C<diag_str()> and C<event()> in
+the C<ZOOM> package itself, and eight classes:
 C<ZOOM::Exception>,
 C<ZOOM::Options>,
 C<ZOOM::Connection>,
@@ -76,7 +76,7 @@ In general, method calls throw an exception if anything goes wrong, so
 you don't need to test for success after each call.  See the section
 below on the Exception class for details.
 
-=head1 UTILITY FUNCTION
+=head1 UTILITY FUNCTIONS
 
 =head2 ZOOM::diag_str()
 
@@ -92,6 +92,21 @@ C<ZOOM::Connection::errcode()>,
 irrespective of whether it is a member of the C<ZOOM::Error>
 enumeration or drawn from the BIB-1 diagnostic set.
 
+=head2 ZOOM::event()
+
+B<Warning: lark's vomit.  Do not read this.>
+
+ $which = ZOOM::event([ $conn1, $conn2, $conn3 ]);
+
+Used only in complex asynchronous applications, this function takes a
+reference to a list of Connection objects, waits until an event
+occurs on any one of them, and returns an integer indicating which of
+the connections it occurred on.  The return value is a 1-based index
+into the list; 0 is returned if no event occurs within the longest
+timeout specified by the C<timeout> options of all the connections.
+
+B<This function is not yet implemented.>
+
 =head1 CLASSES
 
 The eight ZOOM classes are described here in ``sensible order'':
@@ -368,6 +383,19 @@ Creates and returns a new C<ZOOM::Package>, to be used in invoking an
 Extended Service.  An options block may optionally be passed in.  See
 the C<ZOOM::Package> documentation.
 
+=head4 last_event()
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+     print "Connected!\n";
+ }
+
+Returns a C<ZOOM::Event> enumerated value indicating the type of the
+last event that occurred on the connection.  This is used only in
+complex asynchronous applications - see the section below on
+<ZOOM::Event> for more information.
+
+B<Beware - this method has not been tested>
+
 =head4 destroy()
 
  $conn->destroy()