[ViewVC] Diff of: cvs/AnyEvent-MP/MP.pm

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.36 by root, Thu Aug 6 10:46:48 2009 UTC vs.
Revision 1.39 by root, Fri Aug 7 23:21:48 2009 UTC

…		…
8		8
9	$NODE # contains this node's noderef	9	$NODE # contains this node's noderef
10	NODE # returns this node's noderef	10	NODE # returns this node's noderef
11	NODE $port # returns the noderef of the port	11	NODE $port # returns the noderef of the port
12		12
		13	$SELF # receiving/own port id in rcv callbacks
		14
		15	# ports are message endpoints
		16
		17	# sending messages
13	snd $port, type => data...;	18	snd $port, type => data...;
		19	snd $port, @msg;
		20	snd @msg_with_first_element_being_a_port;
14		21
15	$SELF # receiving/own port id in rcv callbacks	22	# miniports
		23	my $miniport = port { my @msg = @_; 0 };
16		24
		25	# full ports
		26	my $port = port;
17	rcv $port, smartmatch => $cb->($port, @msg);	27	rcv $port, smartmatch => $cb->(@msg);
18
19	# examples:
20	rcv $port2, ping => sub { snd $_[0], "pong"; 0 };	28	rcv $port, ping => sub { snd $_[0], "pong"; 0 };
21	rcv $port1, pong => sub { warn "pong received\n" };	29	rcv $port, pong => sub { warn "pong received\n"; 0 };
22	snd $port2, ping => $port1;	30
		31	# remote ports
		32	my $port = spawn $node, $initfunc, @initdata;
23		33
24	# more, smarter, matches (_any_ is exported by this module)	34	# more, smarter, matches (_any_ is exported by this module)
25	rcv $port, [child_died => $pid] => sub { ...	35	rcv $port, [child_died => $pid] => sub { ...
26	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3	36	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
27
28	# linking two ports, so they both crash together
29	lnk $port1, $port2;
30		37
31	# monitoring	38	# monitoring
32	mon $port, $cb->(@msg) # callback is invoked on death	39	mon $port, $cb->(@msg) # callback is invoked on death
33	mon $port, $otherport # kill otherport on abnormal death	40	mon $port, $otherport # kill otherport on abnormal death
34	mon $port, $otherport, @msg # send message on death	41	mon $port, $otherport, @msg # send message on death
…		…
112		119
113	our $VERSION = '0.1';	120	our $VERSION = '0.1';
114	our @EXPORT = qw(	121	our @EXPORT = qw(
115	NODE $NODE *SELF node_of _any_	122	NODE $NODE *SELF node_of _any_
116	resolve_node initialise_node	123	resolve_node initialise_node
117	snd rcv mon kil reg psub	124	snd rcv mon kil reg psub spawn
118	port	125	port
119	);	126	);
120		127
121	our $SELF;	128	our $SELF;
122		129
…		…
343	registered.	350	registered.
344		351
345	The global C<$SELF> (exported by this module) contains C<$port> while	352	The global C<$SELF> (exported by this module) contains C<$port> while
346	executing the callback.	353	executing the callback.
347		354
348	Runtime errors wdurign callback execution will result in the port being	355	Runtime errors during callback execution will result in the port being
349	C<kil>ed.	356	C<kil>ed.
350		357
351	If the match is an array reference, then it will be matched against the	358	If the match is an array reference, then it will be matched against the
352	first elements of the message, otherwise only the first element is being	359	first elements of the message, otherwise only the first element is being
353	matched.	360	matched.
…		…
513	C<$rvport> defaults to C<$SELF>.	520	C<$rvport> defaults to C<$SELF>.
514		521
515	In the last form (message), a message of the form C<@msg, @reason> will be	522	In the last form (message), a message of the form C<@msg, @reason> will be
516	C<snd>.	523	C<snd>.
517		524
		525	As a rule of thumb, monitoring requests should always monitor a port from
		526	a local port (or callback). The reason is that kill messages might get
		527	lost, just like any other message. Another less obvious reason is that
		528	even monitoring requests can get lost (for exmaple, when the connection
		529	to the other node goes down permanently). When monitoring a port locally
		530	these problems do not exist.
		531
518	Example: call a given callback when C<$port> is killed.	532	Example: call a given callback when C<$port> is killed.
519		533
520	mon $port, sub { warn "port died because of <@_>\n" };	534	mon $port, sub { warn "port died because of <@_>\n" };
521		535
522	Example: kill ourselves when C<$port> is killed abnormally.	536	Example: kill ourselves when C<$port> is killed abnormally.
…		…
578	#TODO: mon-less form?	592	#TODO: mon-less form?
579		593
580	mon $port, sub { 0 && @refs }	594	mon $port, sub { 0 && @refs }
581	}	595	}
582		596
583	=item lnk $port1, $port2
584
585	=item lnk $otherport
586
587	Link two ports. This is simply a shorthand for:
588
589	mon $port1, $port2;
590	mon $port2, $port1;
591
592	It means that if either one is killed abnormally, the other one gets
593	killed as well.
594
595	The one-argument form assumes that one port is C<$SELF>.
596
597	=cut
598
599	sub lnk {
600	my $port1 = shift;
601	my $port2 = @_ ? shift : $SELF \|\| Carp::croak 'lnk: called with one argument only, but $SELF not set,';
602
603	mon $port1, $port2;
604	mon $port2, $port1;
605	}
606
607	=item kil $port[, @reason]	597	=item kil $port[, @reason]
608		598
609	Kill the specified port with the given C<@reason>.	599	Kill the specified port with the given C<@reason>.
610		600
611	If no C<@reason> is specified, then the port is killed "normally" (linked	601	If no C<@reason> is specified, then the port is killed "normally" (linked
…		…
617	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks	607	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
618	will be reported as reason C<< die => $@ >>.	608	will be reported as reason C<< die => $@ >>.
619		609
620	Transport/communication errors are reported as C<< transport_error =>	610	Transport/communication errors are reported as C<< transport_error =>
621	$message >>.	611	$message >>.
		612
		613	=cut
		614
		615	=item $port = spawn $node, $initfunc[, @initdata]
		616
		617	Creates a port on the node C<$node> (which can also be a port ID, in which
		618	case it's the node where that port resides).
		619
		620	The port ID of the newly created port is return immediately, and it is
		621	permissible to immediately start sending messages or monitor the port.
		622
		623	After the port has been created, the init function is
		624	called. This function must be a fully-qualified function name
		625	(e.g. C<MyApp::Chat::Server::init>).
		626
		627	If the function doesn't exist, then the node tries to C<require>
		628	the package, then the package above the package and so on (e.g.
		629	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
		630	exists or it runs out of package names.
		631
		632	The init function is then called with the newly-created port as context
		633	object (C<$SELF>) and the C<@initdata> values as arguments.
		634
		635	A common idiom is to pass your own port, monitor the spawned port, and
		636	in the init function, monitor the original port. This two-way monitoring
		637	ensures that both ports get cleaned up when there is a problem.
		638
		639	Example: spawn a chat server port on C<$othernode>.
		640
		641	# this node, executed from within a port context:
		642	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
		643	mon $server;
		644
		645	# init function on C<$othernode>
		646	sub connect {
		647	my ($srcport) = @_;
		648
		649	mon $srcport;
		650
		651	rcv $SELF, sub {
		652	...
		653	};
		654	}
		655
		656	=cut
		657
		658	sub _spawn {
		659	my $port = shift;
		660	my $init = shift;
		661
		662	local $SELF = "$NODE#$port";
		663	eval {
		664	&{ load_func $init }
		665	};
		666	_self_die if $@;
		667	}
		668
		669	sub spawn(@) {
		670	my ($noderef, undef) = split /#/, shift, 2;
		671
		672	my $id = "$RUNIQ." . $ID++;
		673
		674	$_[0] =~ /::/
		675	or Carp::croak "spawn init function must be a fully-qualified name, caught";
		676
		677	($NODE{$noderef} \|\| add_node $noderef)
		678	->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
		679
		680	"$noderef#$id"
		681	}
622		682
623	=back	683	=back
624		684
625	=head1 NODE MESSAGES	685	=head1 NODE MESSAGES
626		686
…		…
759	or I<none>, there is no in-between, so monitoring single processes is	819	or I<none>, there is no in-between, so monitoring single processes is
760	difficult to implement. Monitoring in AEMP is more flexible than in	820	difficult to implement. Monitoring in AEMP is more flexible than in
761	Erlang, as one can choose between automatic kill, exit message or callback	821	Erlang, as one can choose between automatic kill, exit message or callback
762	on a per-process basis.	822	on a per-process basis.
763		823
764	=item * Erlang has different semantics for monitoring and linking, AEMP has the same.	824	=item * Erlang tries to hide remote/local connections, AEMP does not.
765		825
766	Monitoring in Erlang is not an indicator of process death/crashes,	826	Monitoring in Erlang is not an indicator of process death/crashes,
767	as linking is (except linking is unreliable in Erlang). In AEMP, the	827	as linking is (except linking is unreliable in Erlang).
768	semantics of monitoring and linking are identical, linking is simply	828
769	two-way monitoring with automatic kill.	829	In AEMP, you don't "look up" registered port names or send to named ports
		830	that might or might not be persistent. Instead, you normally spawn a port
		831	on the remote node. The init function monitors the you, and you monitor
		832	the remote port. Since both monitors are local to the node, they are much
		833	more reliable.
		834
		835	This also saves round-trips and avoids sending messages to the wrong port
		836	(hard to do in Erlang).
770		837
771	=back	838	=back
772		839
773	=head1 SEE ALSO	840	=head1 SEE ALSO
774		841

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.36 by root, Thu Aug 6 10:46:48 2009 UTC vs. Revision 1.39 by root, Fri Aug 7 23:21:48 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.36 by root, Thu Aug 6 10:46:48 2009 UTC vs.
Revision 1.39 by root, Fri Aug 7 23:21:48 2009 UTC