New
[irspy-moved-to-github.git] / lib / ZOOM / Pod.pm
1 # $Id: Pod.pm,v 1.22 2006-10-06 11:33:07 mike Exp $
2
3 package ZOOM::Pod;
4
5 use strict;
6 use warnings;
7
8 use ZOOM;
9
10 BEGIN {
11     # Just register the names: this doesn't turn the levels on
12     ZOOM::Log::mask_str("pod");
13     ZOOM::Log::mask_str("pod_unhandled");
14 }
15
16 =head1 NAME
17
18 ZOOM::Pod - Perl extension for handling pods of concurrent ZOOM connections
19
20 =head1 SYNOPSIS
21
22  use ZOOM::Pod;
23
24  $pod = new ZOOM::Pod("bagel.indexdata.com/gils",
25                       "bagel.indexdata.com/marc");
26  $pod->callback(ZOOM::Event::RECV_SEARCH, \&completed_search);
27  $pod->callback(ZOOM::Event::RECV_RECORD, \&got_record);
28  $pod->search_pqf("the");
29  $err = $pod->wait();
30  die "$pod->wait() failed with error $err" if $err;
31
32  sub completed_search {
33      ($conn, undef, $rs) = @_;
34      print $conn->option("host"), ": found ", $rs->size(), " records\n";
35      $rs->records(0, 1, 0); # Queues a request for the record
36      return 0;
37  }
38
39  sub got_record {
40      ($conn, undef, $rs) = @_;
41      $rec = $rs->record(0);
42      print $conn->option("host"), ": got $rec = '", $rec->render(), "'\n";
43      return 0;
44  }
45
46 =head1 DESCRIPTION
47
48 C<ZOOM:Pod> provides an API that simplifies asynchronous programming
49 using ZOOM.  A pod is a collection of asynchronous connections that
50 are run simultaneously to achieve broadcast searching and retrieval.
51 When a pod is created, a set of connections (or target-strings to
52 connect to) are specified.  Thereafter, they are treated as a unit,
53 and methods for searching, option-setting, etc. that are invoked on
54 the pod are delegated to each of its members.
55
56 The key method on a pod is C<wait()>, which enters a loop accepting
57 and dispatching events occurring on any of the connections in the pod.
58 Unless interrupted,the loop runs until there are no more events left,
59 i.e. no searches are outstanding and no requested records have still
60 to be received.
61
62 Event dispatching is done by means of callback functions, which can be
63 registered for each event.  A registered callback is invoked whenever
64 a corresponding event occurs.  A special callback can be nominated to
65 handle errors.
66
67 =head1 METHODS
68
69 =head2 new()
70
71  $pod = new ZOOM::Pod($conn1, $conn2, $conn3);
72  $pod = new ZOOM::Pod("bagel.indexdata.com/gils",
73                       "bagel.indexdata.com/marc");
74
75 Creates a new pod containing one or more connections.  Each connection
76 may be specified either by an existing C<ZOOM::Connection> object,
77 which I<must> be asynchronous; or by a ZOOM target string, in which
78 case the pod module will make the connection object itself.
79
80 Returns the new pod.
81
82 =cut
83
84 # Functionality to be added:
85 #
86 #       If the constructor's first argument is a number, then it is
87 #       taken as a limit on the number of connections to handle at any
88 #       one time.  In this case, the pod initially multiplexes between
89 #       the first I<n> connections, and brings further connections
90 #       into the active subset whenever already-active connections are
91 #       closed.
92
93 sub new {
94     my $class = shift();
95     my(@conn) = @_;
96
97     die "$class with no connections" if @conn == 0;
98     foreach my $conn (@conn) {
99         if (!ref $conn) {
100             $conn = new ZOOM::Connection($conn, 0, async => 1);
101             # The $conn object is always made, even if no there's no
102             # server.  Such errors are caught later, by the _check()
103             # call in wait(). 
104         }
105     }
106
107     return bless {
108         conn => \@conn,
109         rs => [],
110         callback => {},
111     }, $class;
112 }
113
114
115 =head2 connections()
116
117  @c = $pod->connections();
118
119 Returns a list of the connection objects in the pod.
120
121 =cut
122
123 sub connections {
124     my $this = shift();
125     return @{ $this->{conn} }
126 }
127
128
129 =head2 option()
130
131  $oldElemSet = $pod->option("elementSetName");
132  $pod->option(elementSetName => "b");
133
134 Sets a specified option in all the connections in a pod.  Returns the
135 old value that the option had in first of the connections in the pod:
136 be aware that this value was not necessarily shared by all the members
137 of the pod ... but that is true often enough to be useful.
138
139 =cut
140
141 sub option {
142     my $this = shift();
143     my($key, $value) = @_;
144
145     my $old = $this->{conn}->[0]->option($key);
146     foreach my $conn (@{ $this->{conn} }) {
147         $conn->option($key, $value);
148     }
149
150     return $old;
151 }
152
153 =head2 callback()
154
155  $pod->callback(ZOOM::Event::RECV_SEARCH, \&completed_search);
156  $pod->callback("exception", sub { print "never mind: $@\n"; return 0 } );
157
158 Registers a callback to be invoked by the pod when an event happens.
159 Callback functions are invoked by C<wait()> (q.v.).
160
161 When registering a callback, the first argument is an event-code - one
162 of those defined in the C<ZOOM::Event> enumeration - and the second is
163 a function reference, or equivalently an inline code-fragment.  It is
164 acceptable to nominate the same function as the callback for multiple
165 events, by multiple invocations of C<callback()>.
166
167 When an event occurs during the execution of C<wait()>, the relevant
168 callback function is called with four arguments: the connection that the
169 event happened on; the argument that was passed into C<wait()>;
170 the result-set associated with the connection (if there is one); and the
171 event-type (so that a single function that handles events of multiple
172 types can switch on the code where necessary).  The callback function
173 can handle the event as it wishes, finishing up by returning an
174 integer.  If this is zero, then C<wait()> continues as normal; if it
175 is anything else, then that value is immediately returned from
176 C<wait()>.
177
178 So a simple event-handler might look like this:
179
180  sub got_event {
181       ($conn, $arg, $rs, $event) = @_;
182       print "event $event on connection ", $conn->option("host"), "\n";
183       print "Found ", $rs->size(), " records\n"
184           if $event == ZOOM::Event::RECV_SEARCH;
185       return 0;
186  }
187
188 In addition to the event-type callbacks discussed above, there is a
189 special callback, C<"exception">, which is invoked if an exception
190 occurs.  This will nearly always be a ZOOM error, but this can be
191 tested using C<$exception-E<gt>isa("ZOOM::Exception")>.  This callback is
192 invoked with the same arguments as described above, except that
193 instead of the event-type, the fourth argument is a copy of the
194 exception, C<$@>.  Exception-handling callbacks may of course re-throw
195 the exception using C<die $exception>.
196
197 So a simple error-handler might look like this:
198
199  sub got_error {
200       ($conn, $arg, $rs, $exception) = @_;
201       if ($exception->isa("ZOOM::Exception")) {
202           print "Caught error $exception - continuing";
203           return 0;
204       }
205       die $exception;
206  }
207
208 The C<$arg> argument could be anything at all - it is whatever the
209 application code passed into C<wait()>.  For example, it could be
210 a reference to a hash indexed by the host string of the connections to
211 yield some per-connection state information.
212 An application might use such information
213 to keep a record of which was the last record
214 retrieved from the associated connection.
215
216 =cut
217
218 sub callback {
219     my $this = shift();
220     my($event, $sub) = @_;
221
222     my $old = $this->{callback}->{$event};
223     $this->{callback}->{$event} = $sub;
224
225     return $old;
226 }
227
228 =head2 remove_callbacks()
229
230  $pod->remove_callbacks();
231
232 Removes all registed callbacks from the pod.  This is useful when the
233 pod has completed one operation and is about to start the next.
234
235 =cut
236
237 sub remove_callbacks {
238     my $this = shift();
239     $this->{callback} = {};
240 }
241
242 =head2 search_pqf()
243
244  $pod->search_pqf("@attr 1=1003 wedel");
245
246 Submits the specified query to each of the connections in a pod,
247 delegating to the same-named method of the C<ZOOM::Connection> class
248 and storing each result in a result-set object associated with the
249 connection that generated it.  Returns no value: success or failure
250 must subsequently be detected by inspecting the events and exceptions
251 generated by C<wait()>ing on the pod.
252
253 B<WARNING!>
254 An important simplifying assumption is that each connection can only
255 have one search active on it at a time: this allows the pod to
256 maintain the one-to-one mapping between connections and result-sets.
257 Submitting a new search on a connection before the old one has
258 completed will result in a total failure in the nature of causality,
259 and the spontaneous existence-failure of the universe.  Try to avoid
260 doing this too often.
261
262 =cut
263
264 sub search_pqf {
265     my $this = shift();
266     my($pqf) = @_;
267
268     foreach my $i (0..@{ $this->{conn} }-1) {
269         my $conn = $this->{conn}->[$i];
270         $this->{rs}->[$i] = $conn->search_pqf($pqf)
271             if !$conn->option("pod_omit");
272     }
273 }
274
275 =head2 wait()
276
277  $err = $pod->wait();
278  # or
279  $err = $pod->wait($arg);
280  die "$pod->wait() failed with error $err" if $err;
281
282 Waits for events on the connections that make up the pod, usually
283 continuing until there are no more events left and then returning
284 zero.  Whenever an event occurs, a callback function is dispatched as
285 described above; if an argument was passed to C<wait()>, then that
286 same argument is also passed to each callback invocation.  If
287 that function returns a non-zero value, then C<wait()> terminates
288 immediately, whether or not any events remain, and returns that value.
289
290 If an error occurs on one of the connection in the pod, then it is
291 normally thrown as a C<ZOOM::Exception>.  If, however, there is a
292 special C<"exception"> callback registered, then the exception object
293 is passed to this instead.  As usual, the return value of the callback
294 indicates whether C<wait()> should continue (return-value 0) or return
295 immediately (any other value).  Exception-handling callbacks may of
296 course re-throw the exception.
297
298 Connections that have the C<pod_omit> option set are omitted from
299 consideration.  This is useful if, for example, a connection that is
300 part of a pod is known to have encountered an unrecoverable error.
301
302 =cut
303
304 sub wait {
305     my $this = shift();
306     my($arg) = @_;
307
308     my $res = 0;
309
310     while (1) {
311         my @conn;
312         my @idxmap; # maps indexes into conn to global indexes
313         foreach my $i (0 .. @{ $this->{conn} }-1) {
314             my $conn = $this->{conn}->[$i];
315             if ($conn->option("pod_omit")) {
316                 #ZOOM::Log::log("pod", "connection $i omitted (",
317                                #$conn->option("host"), ")");
318               } else {
319                   push @conn, $conn;
320                   push @idxmap, $i;
321                   #ZOOM::Log::log("pod", "connection $i included (",
322                                  #$conn->option("host"), ")");
323               }
324         }
325
326         last if @conn == 0;
327         my $i0 = ZOOM::event(\@conn);
328         last if $i0 == 0;
329         my $i = 1+$idxmap[$i0-1];
330         my $conn = $this->{conn}->[$i-1];
331         die "connection-mapping screwup" if $conn ne $conn[$i0-1];
332
333         my $ev = $conn->last_event();
334         my $evstr = ZOOM::event_str($ev);
335         ZOOM::Log::log("pod", "connection ", $i-1, ": event $ev ($evstr)");
336
337         eval {
338             $conn->_check();
339         }; if ($@) {
340             my $sub = $this->{callback}->{exception};
341             die $@ if !defined $sub;
342             $res = &$sub($conn, $arg, $this->{rs}->[$i-1], $@);
343             last if $res != 0;
344             next;
345         }
346
347         my $sub = $this->{callback}->{$ev};
348         if (defined $sub) {
349             $res = &$sub($conn, $arg, $this->{rs}->[$i-1], $ev);
350             last if $res != 0;
351         } else {
352             ZOOM::Log::log("pod_unhandled", "connection ", $i-1, ": unhandled event $ev ($evstr)");
353         }
354     }
355
356     return $res;
357 }
358
359
360 =head1 LOGGING
361
362 This module generates logging messages using C<ZOOM::Log::log()>,
363 which in turn relies on the YAZ logging facilities.  It uses two
364 logging levels:
365
366 =over 4
367
368 =item pod
369
370 Logs all events.
371
372 =item pod_unhandled
373
374 Logs unhandled events, i.e. events of types for which no callback has
375 been registered.
376
377 =back
378
379 These logging levels can be turned on by setting the C<YAZ_LOG>
380 environment variable to C<pod,pod_unhandled>.
381
382 =head1 SEE ALSO
383
384 The underlying
385 C<ZOOM>
386 module (part of the
387 C<Net::Z3950::ZOOM>
388 distribution).
389
390 =head1 AUTHOR
391
392 Mike Taylor, E<lt>mike@indexdata.comE<gt>
393
394 =head1 COPYRIGHT AND LICENCE
395
396 Copyright (C) 2006 by Index Data.
397
398 This library is free software; you can redistribute it and/or modify
399 it under the same terms as Perl itself, either Perl version 5.8.4 or,
400 at your option, any later version of Perl 5 you may have available.
401
402 =cut
403
404
405 1;