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.130 by root, Fri Mar 9 17:05:26 2012 UTC vs.
Revision 1.134 by root, Mon Mar 12 14:47:23 2012 UTC

… …
398 398
399=cut 399=cut
400 400
401sub rcv($@); 401sub rcv($@);
402 402
403sub _kilme { 403my $KILME = sub {
404 die "received message on port without callback"; 404 (my $tag = substr $_[0], 0, 30) =~ s/([\x20-\x7e])/./g;
405} 405 kil $SELF, unhandled_message => "missing (tag or fallback) callback for message '$tag'";
406};
406 407
407sub port(;&) { 408sub port(;&) {
408 my $id = $UNIQ . ++$ID; 409 my $id = $UNIQ . ++$ID;
409 my $port = "$NODE#$id"; 410 my $port = "$NODE#$id";
410 411
411 rcv $port, shift || \&_kilme; 412 rcv $port, shift || $KILME;
412 413
413 $port 414 $port
414} 415}
415 416
416=item rcv $local_port, $callback->(@msg) 417=item rcv $local_port, $callback->(@msg)
… …
421 422
422The global C<$SELF> (exported by this module) contains C<$port> while 423The global C<$SELF> (exported by this module) contains C<$port> while
423executing the callback. Runtime errors during callback execution will 424executing the callback. Runtime errors during callback execution will
424result in the port being C<kil>ed. 425result in the port being C<kil>ed.
425 426
426The default callback received all messages not matched by a more specific 427The default callback receives all messages not matched by a more specific
427C<tag> match. 428C<tag> match.
428 429
429=item rcv $local_port, tag => $callback->(@msg_without_tag), ... 430=item rcv $local_port, tag => $callback->(@msg_without_tag), ...
430 431
431Register (or replace) callbacks to be called on messages starting with the 432Register (or replace) callbacks to be called on messages starting with the
… …
732will be reported as reason C<< die => $@ >>. 733will be reported as reason C<< die => $@ >>.
733 734
734Transport/communication errors are reported as C<< transport_error => 735Transport/communication errors are reported as C<< transport_error =>
735$message >>. 736$message >>.
736 737
737=cut 738Common idioms:
739
740 # silently remove yourself, do not kill linked ports
741 kil $SELF;
742
743 # report a failure in some detail
744 kil $SELF, failure_mode_1 => "it failed with too high temperature";
745
746 # do not waste much time with killing, just die when something goes wrong
747 open my $fh, "<file"
748 or die "file: $!";
738 749
739=item $port = spawn $node, $initfunc[, @initdata] 750=item $port = spawn $node, $initfunc[, @initdata]
740 751
741Creates a port on the node C<$node> (which can also be a port ID, in which 752Creates a port on the node C<$node> (which can also be a port ID, in which
742case it's the node where that port resides). 753case it's the node where that port resides).
… …
894=back 905=back
895 906
896=head1 DISTRIBUTED DATABASE 907=head1 DISTRIBUTED DATABASE
897 908
898AnyEvent::MP comes with a simple distributed database. The database will 909AnyEvent::MP comes with a simple distributed database. The database will
899be mirrored asynchronously at all global nodes. Other nodes bind to one of 910be mirrored asynchronously on all global nodes. Other nodes bind to one
900the global nodes for their needs. 911of the global nodes for their needs. Every node has a "local database"
912which contains all the values that are set locally. All local databases
913are merged together to form the global database, which can be queried.
901 914
902The database consists of a two-level hash - a hash contains a hash which 915The database structure is that of a two-level hash - the database hash
903contains values. 916contains hashes which contain values, similarly to a perl hash of hashes,
917i.e.:
918
919 $DATABASE{$family}{$subkey} = $value
904 920
905The top level hash key is called "family", and the second-level hash key 921The top level hash key is called "family", and the second-level hash key
906is called "subkey" or simply "key". 922is called "subkey" or simply "key".
907 923
908The family must be alphanumeric, i.e. start with a letter and consist 924The family must be alphanumeric, i.e. start with a letter and consist
… …
913with the name of the application or module using it. 929with the name of the application or module using it.
914 930
915The subkeys must be non-empty strings, with no further restrictions. 931The subkeys must be non-empty strings, with no further restrictions.
916 932
917The values should preferably be strings, but other perl scalars should 933The values should preferably be strings, but other perl scalars should
918work as well (such as undef, arrays and hashes). 934work as well (such as C<undef>, arrays and hashes).
919 935
920Every database entry is owned by one node - adding the same family/subkey 936Every database entry is owned by one node - adding the same family/subkey
921combination on multiple nodes will not cause discomfort for AnyEvent::MP, 937combination on multiple nodes will not cause discomfort for AnyEvent::MP,
922but the result might be nondeterministic, i.e. the key might have 938but the result might be nondeterministic, i.e. the key might have
923different values on different nodes. 939different values on different nodes.
… …
985Creates a monitor on the given database family. Each time a key is set 1001Creates a monitor on the given database family. Each time a key is set
986or or is deleted the callback is called with a hash containing the 1002or or is deleted the callback is called with a hash containing the
987database family and three lists of added, changed and deleted subkeys, 1003database family and three lists of added, changed and deleted subkeys,
988respectively. If no keys have changed then the array reference might be 1004respectively. If no keys have changed then the array reference might be
989C<undef> or even missing. 1005C<undef> or even missing.
1006
1007If not called in void context, a guard object is returned that, when
1008destroyed, stops the monitor.
990 1009
991The family hash reference and the key arrays belong to AnyEvent::MP and 1010The family hash reference and the key arrays belong to AnyEvent::MP and
992B<must not be modified or stored> by the callback. When in doubt, make a 1011B<must not be modified or stored> by the callback. When in doubt, make a
993copy. 1012copy.
994 1013

Diff Legend

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