1 # $Id: Pod.pm,v 1.6 2006-05-10 16:44:57 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);
137 It is passed the connection that the event happened on, a state
138 hash-reference associated with the connection, the connection's
139 result-set and the event-type (so that a single function can handle
140 events of multiple types, switching on the code where necessary).
146 my($event, $sub) = @_;
148 my $old = $this->{callback}->{$event};
149 $this->{callback}->{$event} = $sub
160 An important simplifying assumption is that each connection can only
161 have one search active on it at a time - this allows the pod to
162 maintain a one-to-one mapping between connections and result-sets.
170 foreach my $i (0..@{ $this->{conn} }-1) {
171 $this->{rs}->[$i] = $this->{conn}->[$i]->search_pqf($pqf);
185 while ((my $i = ZOOM::event($this->{conn})) != 0) {
186 my $conn = $this->{conn}->[$i-1];
187 my $ev = $conn->last_event();
188 my $evstr = ZOOM::event_str($ev);
189 ZOOM::Log::log("pod", "connection ", $i-1, ": $evstr");
194 my $sub = $this->{callback}->{exception};
195 die $@ if !defined $sub;
196 $res = &$sub($conn, $this->{state}->[$i-1],
197 $this->{rs}->[$i-1], $@);
202 my $sub = $this->{callback}->{$ev};
204 $res = &$sub($conn, $this->{state}->[$i-1],
205 $this->{rs}->[$i-1], $ev);
208 ZOOM::Log::log("pod_unhandled", "unhandled event $ev ($evstr)");
226 Mike Taylor, E<lt>mike@indexdata.comE<gt>
228 =head1 COPYRIGHT AND LICENCE
230 Copyright (C) 2006 by Index Data.
232 This library is free software; you can redistribute it and/or modify
233 it under the same terms as Perl itself, either Perl version 5.8.4 or,
234 at your option, any later version of Perl 5 you may have available.