+=head2 callback()
+
+ $pod->callback(ZOOM::Event::RECV_SEARCH, \&completed_search);
+ $pod->callback("exception", sub { print "never mind: $@\n"; return 0 } );
+
+Registers a callback to be invoked by the pod when an event happens.
+Callback functions are invoked by C<wait()> (q.v.).
+
+When registering a callback, the first argument is an event-code - one
+of those defined in the C<ZOOM::Event> enumeration - and the second is
+a function reference, or equivalently an inline code-fragment. It is
+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 called with four arguments: the connection that the
+event happened on; the argument that was passed into C<wait()>;
+the result-set associated with the connection (if there is one); and the
+event-type (so that a single function that handles events of multiple
+types can switch on the code where necessary). The callback function
+can handle the event as it wishes, finishing up by returning an
+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 simple event-handler might look like this:
+
+ sub got_event {
+ ($conn, $arg, $rs, $event) = @_;
+ print "event $event on connection ", $conn->option("host"), "\n";
+ print "Found ", $rs->size(), " records\n"
+ if $event == ZOOM::Event::RECV_SEARCH;
+ return 0;
+ }
+
+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<$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 $exception>.
+
+So a simple error-handler might look like this:
+
+ sub got_error {
+ ($conn, $arg, $rs, $exception) = @_;
+ if ($exception->isa("ZOOM::Exception")) {
+ print "Caught error $exception - continuing";
+ return 0;
+ }
+ die $exception;
+ }
+
+The C<$arg> argument could be anything at all - it is whatever the
+application code passed into C<wait()>. For example, it could be
+a reference to a hash indexed by the host string of the connections to
+yield some per-connection state information.
+An application might use such information
+to keep a record of which was the last record
+retrieved from the associated connection.
+
+=cut
+