[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.40 by root, Sat Aug 8 00:22:16 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>). To specify a function in the main
		626	program, use C<::name>.
		627
		628	If the function doesn't exist, then the node tries to C<require>
		629	the package, then the package above the package and so on (e.g.
		630	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
		631	exists or it runs out of package names.
		632
		633	The init function is then called with the newly-created port as context
		634	object (C<$SELF>) and the C<@initdata> values as arguments.
		635
		636	A common idiom is to pass your own port, monitor the spawned port, and
		637	in the init function, monitor the original port. This two-way monitoring
		638	ensures that both ports get cleaned up when there is a problem.
		639
		640	Example: spawn a chat server port on C<$othernode>.
		641
		642	# this node, executed from within a port context:
		643	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
		644	mon $server;
		645
		646	# init function on C<$othernode>
		647	sub connect {
		648	my ($srcport) = @_;
		649
		650	mon $srcport;
		651
		652	rcv $SELF, sub {
		653	...
		654	};
		655	}
		656
		657	=cut
		658
		659	sub _spawn {
		660	my $port = shift;
		661	my $init = shift;
		662
		663	local $SELF = "$NODE#$port";
		664	eval {
		665	&{ load_func $init }
		666	};
		667	_self_die if $@;
		668	}
		669
		670	sub spawn(@) {
		671	my ($noderef, undef) = split /#/, shift, 2;
		672
		673	my $id = "$RUNIQ." . $ID++;
		674
		675	$_[0] =~ /::/
		676	or Carp::croak "spawn init function must be a fully-qualified name, caught";
		677
		678	($NODE{$noderef} \|\| add_node $noderef)
		679	->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
		680
		681	"$noderef#$id"
		682	}
622		683
623	=back	684	=back
624		685
625	=head1 NODE MESSAGES	686	=head1 NODE MESSAGES
626		687
…		…
759	or I<none>, there is no in-between, so monitoring single processes is	820	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	821	difficult to implement. Monitoring in AEMP is more flexible than in
761	Erlang, as one can choose between automatic kill, exit message or callback	822	Erlang, as one can choose between automatic kill, exit message or callback
762	on a per-process basis.	823	on a per-process basis.
763		824
764	=item * Erlang has different semantics for monitoring and linking, AEMP has the same.	825	=item * Erlang tries to hide remote/local connections, AEMP does not.
765		826
766	Monitoring in Erlang is not an indicator of process death/crashes,	827	Monitoring in Erlang is not an indicator of process death/crashes,
767	as linking is (except linking is unreliable in Erlang). In AEMP, the	828	as linking is (except linking is unreliable in Erlang).
768	semantics of monitoring and linking are identical, linking is simply	829
769	two-way monitoring with automatic kill.	830	In AEMP, you don't "look up" registered port names or send to named ports
		831	that might or might not be persistent. Instead, you normally spawn a port
		832	on the remote node. The init function monitors the you, and you monitor
		833	the remote port. Since both monitors are local to the node, they are much
		834	more reliable.
		835
		836	This also saves round-trips and avoids sending messages to the wrong port
		837	(hard to do in Erlang).
770		838
771	=back	839	=back
772		840
773	=head1 SEE ALSO	841	=head1 SEE ALSO
774		842

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.40 by root, Sat Aug 8 00:22:16 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.40 by root, Sat Aug 8 00:22:16 2009 UTC