ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP.pm
(Generate patch)

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.31 by root, Wed Aug 5 19:55:58 2009 UTC vs.
Revision 1.32 by root, Wed Aug 5 19:58:46 2009 UTC

… …
188The type of data you can transfer depends on the transport protocol: when 188The type of data you can transfer depends on the transport protocol: when
189JSON is used, then only strings, numbers and arrays and hashes consisting 189JSON is used, then only strings, numbers and arrays and hashes consisting
190of those are allowed (no objects). When Storable is used, then anything 190of those are allowed (no objects). When Storable is used, then anything
191that Storable can serialise and deserialise is allowed, and for the local 191that Storable can serialise and deserialise is allowed, and for the local
192node, anything can be passed. 192node, anything can be passed.
193
194=item kil $portid[, @reason]
195
196Kill the specified port with the given C<@reason>.
197
198If no C<@reason> is specified, then the port is killed "normally" (linked
199ports will not be kileld, or even notified).
200
201Otherwise, linked ports get killed with the same reason (second form of
202C<mon>, see below).
203
204Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
205will be reported as reason C<< die => $@ >>.
206
207Transport/communication errors are reported as C<< transport_error =>
208$message >>.
209
210=item $guard = mon $portid, $cb->(@reason)
211
212=item $guard = mon $portid, $otherport
213
214=item $guard = mon $portid, $otherport, @msg
215
216Monitor the given port and do something when the port is killed.
217
218In the first form, the callback is simply called with any number
219of C<@reason> elements (no @reason means that the port was deleted
220"normally"). Note also that I<< the callback B<must> never die >>, so use
221C<eval> if unsure.
222
223In the second form, the other port will be C<kil>'ed with C<@reason>, iff
224a @reason was specified, i.e. on "normal" kils nothing happens, while
225under all other conditions, the other port is killed with the same reason.
226
227In the last form, a message of the form C<@msg, @reason> will be C<snd>.
228
229Example: call a given callback when C<$port> is killed.
230
231 mon $port, sub { warn "port died because of <@_>\n" };
232
233Example: kill ourselves when C<$port> is killed abnormally.
234
235 mon $port, $self;
236
237Example: send us a restart message another C<$port> is killed.
238
239 mon $port, $self => "restart";
240
241=cut
242
243sub mon {
244 my ($noderef, $port) = split /#/, shift, 2;
245
246 my $node = $NODE{$noderef} || add_node $noderef;
247
248 my $cb = shift;
249
250 unless (ref $cb) {
251 if (@_) {
252 # send a kill info message
253 my (@msg) = ($cb, @_);
254 $cb = sub { snd @msg, @_ };
255 } else {
256 # simply kill other port
257 my $port = $cb;
258 $cb = sub { kil $port, @_ if @_ };
259 }
260 }
261
262 $node->monitor ($port, $cb);
263
264 defined wantarray
265 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) }
266}
267
268=item $guard = mon_guard $port, $ref, $ref...
269
270Monitors the given C<$port> and keeps the passed references. When the port
271is killed, the references will be freed.
272
273Optionally returns a guard that will stop the monitoring.
274
275This function is useful when you create e.g. timers or other watchers and
276want to free them when the port gets killed:
277
278 $port->rcv (start => sub {
279 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub {
280 undef $timer if 0.9 < rand;
281 });
282 });
283
284=cut
285
286sub mon_guard {
287 my ($port, @refs) = @_;
288
289 mon $port, sub { 0 && @refs }
290}
291
292=item lnk $port1, $port2
293
294Link two ports. This is simply a shorthand for:
295
296 mon $port1, $port2;
297 mon $port2, $port1;
298
299It means that if either one is killed abnormally, the other one gets
300killed as well.
301 193
302=item $local_port = port 194=item $local_port = port
303 195
304Create a new local port object that can be used either as a pattern 196Create a new local port object that can be used either as a pattern
305matching port ("full port") or a single-callback port ("miniport"), 197matching port ("full port") or a single-callback port ("miniport"),
… …
399 291
400=item rcv $portid, $smartmatch => $callback->(@msg), ... 292=item rcv $portid, $smartmatch => $callback->(@msg), ...
401 293
402=item rcv $portid, [$smartmatch...] => $callback->(@msg), ... 294=item rcv $portid, [$smartmatch...] => $callback->(@msg), ...
403 295
404Register callbacks to be called on matching messages on the given port. 296Register callbacks to be called on matching messages on the given full
297port (or newly created port).
405 298
406The callback has to return a true value when its work is done, after 299The callback has to return a true value when its work is done, after
407which is will be removed, or a false value in which case it will stay 300which is will be removed, or a false value in which case it will stay
408registered. 301registered.
409 302
… …
493 $res 386 $res
494 } 387 }
495 } 388 }
496} 389}
497 390
391=item $guard = mon $portid, $cb->(@reason)
392
393=item $guard = mon $portid, $otherport
394
395=item $guard = mon $portid, $otherport, @msg
396
397Monitor the given port and do something when the port is killed.
398
399In the first form, the callback is simply called with any number
400of C<@reason> elements (no @reason means that the port was deleted
401"normally"). Note also that I<< the callback B<must> never die >>, so use
402C<eval> if unsure.
403
404In the second form, the other port will be C<kil>'ed with C<@reason>, iff
405a @reason was specified, i.e. on "normal" kils nothing happens, while
406under all other conditions, the other port is killed with the same reason.
407
408In the last form, a message of the form C<@msg, @reason> will be C<snd>.
409
410Example: call a given callback when C<$port> is killed.
411
412 mon $port, sub { warn "port died because of <@_>\n" };
413
414Example: kill ourselves when C<$port> is killed abnormally.
415
416 mon $port, $self;
417
418Example: send us a restart message another C<$port> is killed.
419
420 mon $port, $self => "restart";
421
422=cut
423
424sub mon {
425 my ($noderef, $port) = split /#/, shift, 2;
426
427 my $node = $NODE{$noderef} || add_node $noderef;
428
429 my $cb = shift;
430
431 unless (ref $cb) {
432 if (@_) {
433 # send a kill info message
434 my (@msg) = ($cb, @_);
435 $cb = sub { snd @msg, @_ };
436 } else {
437 # simply kill other port
438 my $port = $cb;
439 $cb = sub { kil $port, @_ if @_ };
440 }
441 }
442
443 $node->monitor ($port, $cb);
444
445 defined wantarray
446 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) }
447}
448
449=item $guard = mon_guard $port, $ref, $ref...
450
451Monitors the given C<$port> and keeps the passed references. When the port
452is killed, the references will be freed.
453
454Optionally returns a guard that will stop the monitoring.
455
456This function is useful when you create e.g. timers or other watchers and
457want to free them when the port gets killed:
458
459 $port->rcv (start => sub {
460 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub {
461 undef $timer if 0.9 < rand;
462 });
463 });
464
465=cut
466
467sub mon_guard {
468 my ($port, @refs) = @_;
469
470 mon $port, sub { 0 && @refs }
471}
472
473=item lnk $port1, $port2
474
475Link two ports. This is simply a shorthand for:
476
477 mon $port1, $port2;
478 mon $port2, $port1;
479
480It means that if either one is killed abnormally, the other one gets
481killed as well.
482
483=item kil $portid[, @reason]
484
485Kill the specified port with the given C<@reason>.
486
487If no C<@reason> is specified, then the port is killed "normally" (linked
488ports will not be kileld, or even notified).
489
490Otherwise, linked ports get killed with the same reason (second form of
491C<mon>, see below).
492
493Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
494will be reported as reason C<< die => $@ >>.
495
496Transport/communication errors are reported as C<< transport_error =>
497$message >>.
498
498=back 499=back
499 500
500=head1 FUNCTIONS FOR NODES 501=head1 FUNCTIONS FOR NODES
501 502
502=over 4 503=over 4

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines