1 # $Id: Pod.pm,v 1.8 2006-05-12 11:37:48 mike Exp $
11 # Just register the name
12 ZOOM::Log::mask_str("pod");
13 ZOOM::Log::mask_str("pod_unhandled");
18 ZOOM::Pod - Perl extension for handling pods of concurrent ZOOM connections
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");
30 die "$pod->wait() failed with error $err" if $err;
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
40 ($conn, undef, $rs) = @_;
41 $rec = $rs->record(0);
42 print $conn->option("host"), ": got $rec = '", $rec->render(), "'\n";
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.
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
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
71 $pod = new ZOOM::Pod($conn1, $conn2, $conn3);
72 $pod = new ZOOM::Pod("bagel.indexdata.com/gils",
73 "bagel.indexdata.com/marc");
76 Creates a new pod containing one or more connections. Each connection
77 may be specified either by an existing C<ZOOM::Connection> object,
78 which I<must> be asynchronous; or by a ZOOM target string, in which
79 case the pod module will make the connection object itself.
89 die "$class with no connections" if @conn == 0;
90 my @state; # Hashrefs with application state associated with connections
91 foreach my $conn (@conn) {
93 $conn = new ZOOM::Connection($conn, 0, async => 1);
94 # The $conn object is always made, even if no there's no
95 # server. Such errors are caught later, by the _check()
111 $oldElemSet = $pod->option("elementSetName");
112 $pod->option(elementSetName => "b");
114 Sets a specified option in all the connections in a pod. Returns the
115 old value that the option had in first of the connections in the pod:
116 be aware that this value was not necessarily shared by all the members
117 of the pod ... but that is true often enough to be useful.
123 my($key, $value) = @_;
125 my $old = $this->{conn}->[0]->option($key);
126 foreach my $conn (@{ $this->{conn} }) {
127 $conn->option($key, $value);
135 $pod->callback(ZOOM::Event::RECV_SEARCH, \&completed_search);
136 $pod->callback("exception", sub { print "never mind: $@\n"; return 0 } );
138 Registers a callback to be invoked by the pod when an event happens.
139 Callback functions are invoked by C<wait()> (q.v.).
141 When registering a callback, the first argument is an event-code - one
142 of those defined in the C<ZOOM::Event> enumeration - and the second is
143 a function reference, or equivalently an inline code-fragment. It is
144 acceptable to nominate the same function as the callback for multiple
145 events, by multiple invocations of C<callback()>.
147 When an event occurs during the execution of C<wait()>, the relevant
148 callback function is passed four arguments: the connection that the
149 event happened on; a state hash-reference associated with the
150 connection; the result-set associated with the connection; and the
151 event-type (so that a single function that handles events of multiple
152 types can switch on the code where necessary). The callback function
153 can handle the event as it wishes, finishing up by returning an
154 integer. If this is zero, then C<wait()> continues as normal; if it
155 is anything else, then that value is immediately returned from
158 So a typical, simple, event-handler might look like this:
161 ($conn, $state, $rs, $event) = @_;
162 print "event $event on connection ", $conn->option("host"), "\n";
163 print "Found ", $rs->size(), " records\n"
164 if $event == ZOOM::Event::RECV_SEARCH;
168 In addition to the event-type callbacks discussed above, there is a
169 special callback, C<"exception">, which is invoked if an exception
170 occurs. This will nearly always be a ZOOM error, but this can be
171 tested using C<ref($@) eq "ZOOM::Exception">. This callback is
172 invoked with the same arguments as described above, except that
173 instead of the event-type, the fourth argument is a copy of the
174 exception, C<$@>. Exception-handling callbacks may of course re-throw
175 the exception using C<die $@>.
177 So a simple error-handler might look like this:
180 ($conn, $state, $rs, $exception) = @_;
181 if ($exception->isa("ZOOM::Exception")) {
182 print "Caught error $exception -- continuing";
188 The C<$state> argument is a reference to an initially empty hash,
189 which the application can use as it sees fit, to store its own
190 connection-relation information. For example, an application might
191 use C<$state->{last}> to keep a record of which was the last record is
192 retrieved from the associated connection. The pod module itself does
193 not use the state hash at all, and applications are also welcome to
194 ignore it if they do not need it.
200 my($event, $sub) = @_;
202 my $old = $this->{callback}->{$event};
203 $this->{callback}->{$event} = $sub
211 $pod->search_pqf("@attr 1=1003 wedel");
213 Submits the specified query to each of the connections in a pod,
214 delegating to the same-named method of the C<ZOOM::Connection> class
215 and storing eacdh result in a result-set object associated with the
216 connection that generated it. Returns no value: success or failure
217 must subsequently be detected by the events and exceptions generated
218 by C<wait()>ing on the pod.
221 An important simplifying assumption is that each connection can only
222 have one search active on it at a time - this allows the pod to
223 maintain the one-to-one mapping between connections and result-sets.
224 Submitting a new search on a connection before the old one has
225 complete will result in a total failure in the nature of causality,
226 and the spontaneous existence-failure of the universe. Do not do
235 foreach my $i (0..@{ $this->{conn} }-1) {
236 $this->{rs}->[$i] = $this->{conn}->[$i]->search_pqf($pqf);
243 die "$pod->wait() failed with error $err" if $err;
245 Waits for events on the connections that make up the pod, usually
246 continuing until there are no more events left and then returning
247 zero. Whenever an event occurs, a callback function is dispatched as
248 described above in the documentation of the C<callback()> method; if
249 that function returns a non-zero value, then C<wait()> terminates
250 immediately, whether or not any events remain, and returns that value.
252 If an error occurs on one of the connection in the pod, then it is
253 normally thrown as a <ZOOM::Exception>. If, however, there is a
254 special C<"exception"> callback registered, then the exception object
255 is passed to this instead. As usual, the return value of the callback
256 indicates whether C<wait()> should continue (return-value 0) or return
257 immediately (any other value). Exception-handling callbacks may of
258 course re-throw the exception.
266 while ((my $i = ZOOM::event($this->{conn})) != 0) {
267 my $conn = $this->{conn}->[$i-1];
268 my $ev = $conn->last_event();
269 my $evstr = ZOOM::event_str($ev);
270 ZOOM::Log::log("pod", "connection ", $i-1, ": $evstr");
275 my $sub = $this->{callback}->{exception};
276 die $@ if !defined $sub;
277 $res = &$sub($conn, $this->{state}->[$i-1],
278 $this->{rs}->[$i-1], $@);
283 my $sub = $this->{callback}->{$ev};
285 $res = &$sub($conn, $this->{state}->[$i-1],
286 $this->{rs}->[$i-1], $ev);
289 ZOOM::Log::log("pod_unhandled", "unhandled event $ev ($evstr)");
299 This module generates logging messages using C<ZOOM::Log::log()>,
300 which in turn relies on the YAZ logging facilities. It uses two
311 Logs unhandled events, i.e. events of types for which no callback has
316 These logging levels can be turned on by setting the C<YAZ_LOG>
317 environment variable to C<pod,pod_unhandled>.
329 Mike Taylor, E<lt>mike@indexdata.comE<gt>
331 =head1 COPYRIGHT AND LICENCE
333 Copyright (C) 2006 by Index Data.
335 This library is free software; you can redistribute it and/or modify
336 it under the same terms as Perl itself, either Perl version 5.8.4 or,
337 at your option, any later version of Perl 5 you may have available.