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 a8f6d79..dd6e14c 100644 (file)
--- a/lib/ZOOM/Pod.pm
+++ b/lib/ZOOM/Pod.pm
@@ -1,4 +1,4 @@
-# $Id: Pod.pm,v 1.8 2006-05-12 11:37:48 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,18 +168,18 @@ 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;
@@ -188,7 +188,7 @@ So a simple error-handler might look like this:
 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->{last}> to keep a record of which was the last record is
+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.
@@ -212,17 +212,17 @@ sub callback {
 
 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 eacdh result in a result-set object associated with the
+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 the events and exceptions generated
-by C<wait()>ing on the pod.
+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
+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
-complete will result in a total failure in the nature of causality,
+completed will result in a total failure in the nature of causality,
 and the spontaneous existence-failure of the universe.  Do not do
 this.
 
@@ -245,12 +245,12 @@ sub search_pqf {
 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 in the documentation of the C<callback()> method; if
+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 <ZOOM::Exception>.  If, however, there is a
+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
@@ -267,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();
@@ -286,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)");
        }
     }