Consistent formatting for different ZOOM::Log::log() calls.

[irspy-moved-to-github.git] / lib / ZOOM / Pod.pm

diff --git a/lib/ZOOM/Pod.pm b/lib/ZOOM/Pod.pm
index 1c292c8..dd6e14c 100644 (file)
--- a/lib/ZOOM/Pod.pm
+++ b/lib/ZOOM/Pod.pm
@@ -1,4 +1,4 @@
-# $Id: Pod.pm,v 1.7 2006-05-11 15:51:36 mike Exp $
+# $Id: Pod.pm,v 1.10 2006-05-12 13:31:00 mike Exp $
 
 package ZOOM::Pod;
 
@@ -145,7 +145,7 @@ acceptable to nominate the same function as the callback for multiple
 events, by multiple invocations of C<callback()>.
 
 When an event occurs during the execution of C<wait()>, the relevant
-callback function is passed four arguments: the connection that the
+callback function is called with four arguments: the connection that the
 event happened on; a state hash-reference associated with the
 connection; the result-set associated with the connection; and the
 event-type (so that a single function that handles events of multiple
@@ -155,7 +155,7 @@ integer.  If this is zero, then C<wait()> continues as normal; if it
 is anything else, then that value is immediately returned from
 C<wait()>.
 
-So a typical, simple, event-handler might look like this:
+So a simple event-handler might look like this:
 
  sub got_event {
       ($conn, $state, $rs, $event) = @_;
@@ -168,24 +168,30 @@ So a typical, simple, event-handler might look like this:
 In addition to the event-type callbacks discussed above, there is a
 special callback, C<"exception">, which is invoked if an exception
 occurs.  This will nearly always be a ZOOM error, but this can be
-tested using C<ref($@) eq "ZOOM::Exception">.  This callback is
+tested using C<$exception-E<gt>isa("ZOOM::Exception")>.  This callback is
 invoked with the same arguments as described above, except that
 instead of the event-type, the fourth argument is a copy of the
 exception, C<$@>.  Exception-handling callbacks may of course re-throw
-the exception using C<die $@>.
+the exception using C<die $exception>.
 
 So a simple error-handler might look like this:
 
  sub got_error {
       ($conn, $state, $rs, $exception) = @_;
       if ($exception->isa("ZOOM::Exception")) {
-          print "Caught error $exception -- continuing";
+          print "Caught error $exception - continuing";
           return 0;
       }
       die $exception;
  }
 
-I<### state>
+The C<$state> argument is a reference to an initially empty hash,
+which the application can use as it sees fit, to store its own
+connection-relation information.  For example, an application might
+use C<$state-E<gt>{last}> to keep a record of which was the last record
+retrieved from the associated connection.  The pod module itself does
+not use the state hash at all, and applications are also welcome to
+ignore it if they do not need it.
 
 =cut
 
@@ -202,12 +208,23 @@ sub callback {
 
 =head2 search_pqf()
 
-I<###>
+ $pod->search_pqf("@attr 1=1003 wedel");
+
+Submits the specified query to each of the connections in a pod,
+delegating to the same-named method of the C<ZOOM::Connection> class
+and storing each result in a result-set object associated with the
+connection that generated it.  Returns no value: success or failure
+must subsequently be detected by inspecting the events and exceptions
+generated by C<wait()>ing on the pod.
 
 B<WARNING!>
 An important simplifying assumption is that each connection can only
-have one search active on it at a time - this allows the pod to
-maintain a one-to-one mapping between connections and result-sets.  
+have one search active on it at a time: this allows the pod to
+maintain the one-to-one mapping between connections and result-sets.
+Submitting a new search on a connection before the old one has
+completed will result in a total failure in the nature of causality,
+and the spontaneous existence-failure of the universe.  Do not do
+this.
 
 =cut
 
@@ -222,7 +239,23 @@ sub search_pqf {
 
 =head2 wait()
 
-I<###>
+ $err = $pod->wait();
+ die "$pod->wait() failed with error $err" if $err;
+
+Waits for events on the connections that make up the pod, usually
+continuing until there are no more events left and then returning
+zero.  Whenever an event occurs, a callback function is dispatched as
+described above; if
+that function returns a non-zero value, then C<wait()> terminates
+immediately, whether or not any events remain, and returns that value.
+
+If an error occurs on one of the connection in the pod, then it is
+normally thrown as a C<ZOOM::Exception>.  If, however, there is a
+special C<"exception"> callback registered, then the exception object
+is passed to this instead.  As usual, the return value of the callback
+indicates whether C<wait()> should continue (return-value 0) or return
+immediately (any other value).  Exception-handling callbacks may of
+course re-throw the exception.
 
 =cut
 
@@ -234,7 +267,7 @@ sub wait {
        my $conn = $this->{conn}->[$i-1];
        my $ev = $conn->last_event();
        my $evstr = ZOOM::event_str($ev);
-       ZOOM::Log::log("pod", "connection ", $i-1, ": $evstr");
+       ZOOM::Log::log("pod", "connection ", $i-1, ": event $ev ($evstr)");
 
        eval {
            $conn->_check();
@@ -253,7 +286,7 @@ sub wait {
                         $this->{rs}->[$i-1], $ev);
            last if $res != 0;
        } else {
-           ZOOM::Log::log("pod_unhandled", "unhandled event $ev ($evstr)");
+           ZOOM::Log::log("pod_unhandled", "connection ", $i-1, ": unhandled event $ev ($evstr)");
        }
     }
 
@@ -261,6 +294,28 @@ sub wait {
 }
 
 
+=head1 LOGGING
+
+This module generates logging messages using C<ZOOM::Log::log()>,
+which in turn relies on the YAZ logging facilities.  It uses two
+logging levels:
+
+=over 4
+
+=item pod
+
+Logs all events.
+
+=item pod_unhandled
+
+Logs unhandled events, i.e. events of types for which no callback has
+been registered.
+
+=back
+
+These logging levels can be turned on by setting the C<YAZ_LOG>
+environment variable to C<pod,pod_unhandled>.
+
 =head1 SEE ALSO
 
 The underlying