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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.34 by root, Wed Aug 5 23:50:46 2009 UTC vs.
Revision 1.44 by root, Wed Aug 12 21:39:58 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
		37
		38	# monitoring
		39	mon $port, $cb->(@msg) # callback is invoked on death
		40	mon $port, $otherport # kill otherport on abnormal death
		41	mon $port, $otherport, @msg # send message on death
27		42
28	=head1 DESCRIPTION	43	=head1 DESCRIPTION
29		44
30	This module (-family) implements a simple message passing framework.	45	This module (-family) implements a simple message passing framework.
31		46
…		…
90		105
91	=cut	106	=cut
92		107
93	package AnyEvent::MP;	108	package AnyEvent::MP;
94		109
95	use AnyEvent::MP::Base;	110	use AnyEvent::MP::Kernel;
96		111
97	use common::sense;	112	use common::sense;
98		113
99	use Carp ();	114	use Carp ();
100		115
101	use AE ();	116	use AE ();
102		117
103	use base "Exporter";	118	use base "Exporter";
104		119
105	our $VERSION = '0.1';	120	our $VERSION = $AnyEvent::MP::Kernel::VERSION;
		121
106	our @EXPORT = qw(	122	our @EXPORT = qw(
107	NODE $NODE *SELF node_of _any_	123	NODE $NODE *SELF node_of _any_
108	resolve_node initialise_node	124	resolve_node initialise_node
109	snd rcv mon kil reg psub	125	snd rcv mon kil reg psub spawn
110	port	126	port
111	);	127	);
112		128
113	our $SELF;	129	our $SELF;
114		130
…		…
297	$port	313	$port
298	}	314	}
299		315
300	=item reg $port, $name	316	=item reg $port, $name
301		317
302	Registers the given port under the name C<$name>. If the name already	318	=item reg $name
303	exists it is replaced.	319
		320	Registers the given port (or C<$SELF><<< if missing) under the name
		321	C<$name>. If the name already exists it is replaced.
304		322
305	A port can only be registered under one well known name.	323	A port can only be registered under one well known name.
306		324
307	A port automatically becomes unregistered when it is killed.	325	A port automatically becomes unregistered when it is killed.
308		326
309	=cut	327	=cut
310		328
311	sub reg(@) {	329	sub reg(@) {
312	my ($port, $name) = @_;	330	my $port = @_ > 1 ? shift : $SELF \|\| Carp::croak 'reg: called with one argument only, but $SELF not set,';
313		331
314	$REG{$name} = $port;	332	$REG{$_[0]} = $port;
315	}	333	}
316		334
317	=item rcv $port, $callback->(@msg)	335	=item rcv $port, $callback->(@msg)
318		336
319	Replaces the callback on the specified miniport (after converting it to	337	Replaces the callback on the specified miniport (after converting it to
…		…
324	=item rcv $port, $smartmatch => $callback->(@msg), ...	342	=item rcv $port, $smartmatch => $callback->(@msg), ...
325		343
326	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...	344	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...
327		345
328	Register callbacks to be called on matching messages on the given full	346	Register callbacks to be called on matching messages on the given full
329	port (after converting it to one if required).	347	port (after converting it to one if required) and return the port.
330		348
331	The callback has to return a true value when its work is done, after	349	The callback has to return a true value when its work is done, after
332	which is will be removed, or a false value in which case it will stay	350	which is will be removed, or a false value in which case it will stay
333	registered.	351	registered.
334		352
335	The global C<$SELF> (exported by this module) contains C<$port> while	353	The global C<$SELF> (exported by this module) contains C<$port> while
336	executing the callback.	354	executing the callback.
337		355
338	Runtime errors wdurign callback execution will result in the port being	356	Runtime errors during callback execution will result in the port being
339	C<kil>ed.	357	C<kil>ed.
340		358
341	If the match is an array reference, then it will be matched against the	359	If the match is an array reference, then it will be matched against the
342	first elements of the message, otherwise only the first element is being	360	first elements of the message, otherwise only the first element is being
343	matched.	361	matched.
…		…
346	exported by this module) matches any single element of the message.	364	exported by this module) matches any single element of the message.
347		365
348	While not required, it is highly recommended that the first matching	366	While not required, it is highly recommended that the first matching
349	element is a string identifying the message. The one-string-only match is	367	element is a string identifying the message. The one-string-only match is
350	also the most efficient match (by far).	368	also the most efficient match (by far).
		369
		370	Example: create a port and bind receivers on it in one go.
		371
		372	my $port = rcv port,
		373	msg1 => sub { ...; 0 },
		374	msg2 => sub { ...; 0 },
		375	;
		376
		377	Example: create a port, bind receivers and send it in a message elsewhere
		378	in one go:
		379
		380	snd $otherport, reply =>
		381	rcv port,
		382	msg1 => sub { ...; 0 },
		383	...
		384	;
351		385
352	=cut	386	=cut
353		387
354	sub rcv($@) {	388	sub rcv($@) {
355	my $port = shift;	389	my $port = shift;
…		…
462	}	496	}
463	}	497	}
464		498
465	=item $guard = mon $port, $cb->(@reason)	499	=item $guard = mon $port, $cb->(@reason)
466		500
467	=item $guard = mon $port, $otherport	501	=item $guard = mon $port, $rcvport
468		502
		503	=item $guard = mon $port
		504
469	=item $guard = mon $port, $otherport, @msg	505	=item $guard = mon $port, $rcvport, @msg
470		506
471	Monitor the given port and do something when the port is killed.	507	Monitor the given port and do something when the port is killed or
		508	messages to it were lost, and optionally return a guard that can be used
		509	to stop monitoring again.
472		510
		511	C<mon> effectively guarantees that, in the absence of hardware failures,
		512	that after starting the monitor, either all messages sent to the port
		513	will arrive, or the monitoring action will be invoked after possible
		514	message loss has been detected. No messages will be lost "in between"
		515	(after the first lost message no further messages will be received by the
		516	port). After the monitoring action was invoked, further messages might get
		517	delivered again.
		518
473	In the first form, the callback is simply called with any number	519	In the first form (callback), the callback is simply called with any
474	of C<@reason> elements (no @reason means that the port was deleted	520	number of C<@reason> elements (no @reason means that the port was deleted
475	"normally"). Note also that I<< the callback B<must> never die >>, so use	521	"normally"). Note also that I<< the callback B<must> never die >>, so use
476	C<eval> if unsure.	522	C<eval> if unsure.
477		523
478	In the second form, the other port will be C<kil>'ed with C<@reason>, iff	524	In the second form (another port given), the other port (C<$rcvport>)
479	a @reason was specified, i.e. on "normal" kils nothing happens, while	525	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
480	under all other conditions, the other port is killed with the same reason.	526	"normal" kils nothing happens, while under all other conditions, the other
		527	port is killed with the same reason.
481		528
		529	The third form (kill self) is the same as the second form, except that
		530	C<$rvport> defaults to C<$SELF>.
		531
482	In the last form, a message of the form C<@msg, @reason> will be C<snd>.	532	In the last form (message), a message of the form C<@msg, @reason> will be
		533	C<snd>.
		534
		535	As a rule of thumb, monitoring requests should always monitor a port from
		536	a local port (or callback). The reason is that kill messages might get
		537	lost, just like any other message. Another less obvious reason is that
		538	even monitoring requests can get lost (for exmaple, when the connection
		539	to the other node goes down permanently). When monitoring a port locally
		540	these problems do not exist.
483		541
484	Example: call a given callback when C<$port> is killed.	542	Example: call a given callback when C<$port> is killed.
485		543
486	mon $port, sub { warn "port died because of <@_>\n" };	544	mon $port, sub { warn "port died because of <@_>\n" };
487		545
488	Example: kill ourselves when C<$port> is killed abnormally.	546	Example: kill ourselves when C<$port> is killed abnormally.
489		547
490	mon $port, $self;	548	mon $port;
491		549
492	Example: send us a restart message another C<$port> is killed.	550	Example: send us a restart message when another C<$port> is killed.
493		551
494	mon $port, $self => "restart";	552	mon $port, $self => "restart";
495		553
496	=cut	554	=cut
497		555
498	sub mon {	556	sub mon {
499	my ($noderef, $port) = split /#/, shift, 2;	557	my ($noderef, $port) = split /#/, shift, 2;
500		558
501	my $node = $NODE{$noderef} \|\| add_node $noderef;	559	my $node = $NODE{$noderef} \|\| add_node $noderef;
502		560
503	my $cb = shift;	561	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
504		562
505	unless (ref $cb) {	563	unless (ref $cb) {
506	if (@_) {	564	if (@_) {
507	# send a kill info message	565	# send a kill info message
508	my (@msg) = ($cb, @_);	566	my (@msg) = ($cb, @_);
…		…
539	=cut	597	=cut
540		598
541	sub mon_guard {	599	sub mon_guard {
542	my ($port, @refs) = @_;	600	my ($port, @refs) = @_;
543		601
		602	#TODO: mon-less form?
		603
544	mon $port, sub { 0 && @refs }	604	mon $port, sub { 0 && @refs }
545	}	605	}
546		606
547	=item lnk $port1, $port2
548
549	Link two ports. This is simply a shorthand for:
550
551	mon $port1, $port2;
552	mon $port2, $port1;
553
554	It means that if either one is killed abnormally, the other one gets
555	killed as well.
556
557	=item kil $port[, @reason]	607	=item kil $port[, @reason]
558		608
559	Kill the specified port with the given C<@reason>.	609	Kill the specified port with the given C<@reason>.
560		610
561	If no C<@reason> is specified, then the port is killed "normally" (linked	611	If no C<@reason> is specified, then the port is killed "normally" (linked
…		…
567	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks	617	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
568	will be reported as reason C<< die => $@ >>.	618	will be reported as reason C<< die => $@ >>.
569		619
570	Transport/communication errors are reported as C<< transport_error =>	620	Transport/communication errors are reported as C<< transport_error =>
571	$message >>.	621	$message >>.
		622
		623	=cut
		624
		625	=item $port = spawn $node, $initfunc[, @initdata]
		626
		627	Creates a port on the node C<$node> (which can also be a port ID, in which
		628	case it's the node where that port resides).
		629
		630	The port ID of the newly created port is return immediately, and it is
		631	permissible to immediately start sending messages or monitor the port.
		632
		633	After the port has been created, the init function is
		634	called. This function must be a fully-qualified function name
		635	(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main
		636	program, use C<::name>.
		637
		638	If the function doesn't exist, then the node tries to C<require>
		639	the package, then the package above the package and so on (e.g.
		640	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
		641	exists or it runs out of package names.
		642
		643	The init function is then called with the newly-created port as context
		644	object (C<$SELF>) and the C<@initdata> values as arguments.
		645
		646	A common idiom is to pass your own port, monitor the spawned port, and
		647	in the init function, monitor the original port. This two-way monitoring
		648	ensures that both ports get cleaned up when there is a problem.
		649
		650	Example: spawn a chat server port on C<$othernode>.
		651
		652	# this node, executed from within a port context:
		653	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
		654	mon $server;
		655
		656	# init function on C<$othernode>
		657	sub connect {
		658	my ($srcport) = @_;
		659
		660	mon $srcport;
		661
		662	rcv $SELF, sub {
		663	...
		664	};
		665	}
		666
		667	=cut
		668
		669	sub _spawn {
		670	my $port = shift;
		671	my $init = shift;
		672
		673	local $SELF = "$NODE#$port";
		674	eval {
		675	&{ load_func $init }
		676	};
		677	_self_die if $@;
		678	}
		679
		680	sub spawn(@) {
		681	my ($noderef, undef) = split /#/, shift, 2;
		682
		683	my $id = "$RUNIQ." . $ID++;
		684
		685	$_[0] =~ /::/
		686	or Carp::croak "spawn init function must be a fully-qualified name, caught";
		687
		688	($NODE{$noderef} \|\| add_node $noderef)
		689	->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
		690
		691	"$noderef#$id"
		692	}
572		693
573	=back	694	=back
574		695
575	=head1 NODE MESSAGES	696	=head1 NODE MESSAGES
576		697
…		…
618		739
619	=back	740	=back
620		741
621	=head1 AnyEvent::MP vs. Distributed Erlang	742	=head1 AnyEvent::MP vs. Distributed Erlang
622		743
623	AnyEvent::MP got lots of its ideas from distributed erlang (erlang node	744	AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
624	== aemp node, erlang process == aemp port), so many of the documents and	745	== aemp node, Erlang process == aemp port), so many of the documents and
625	programming techniques employed by erlang apply to AnyEvent::MP. Here is a	746	programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
626	sample:	747	sample:
627		748
628	http://www.erlang.se/doc/programming_rules.shtml	749	http://www.Erlang.se/doc/programming_rules.shtml
629	http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4	750	http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
630	http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6	751	http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6
631	http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5	752	http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
632		753
633	Despite the similarities, there are also some important differences:	754	Despite the similarities, there are also some important differences:
634		755
635	=over 4	756	=over 4
636		757
…		…
647		768
648	Erlang uses processes that selctively receive messages, and therefore	769	Erlang uses processes that selctively receive messages, and therefore
649	needs a queue. AEMP is event based, queuing messages would serve no useful	770	needs a queue. AEMP is event based, queuing messages would serve no useful
650	purpose.	771	purpose.
651		772
652	(But see L<Coro::MP> for a more erlang-like process model on top of AEMP).	773	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
653		774
654	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	775	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
655		776
656	Sending messages in erlang is synchronous and blocks the process. AEMP	777	Sending messages in Erlang is synchronous and blocks the process. AEMP
657	sends are immediate, connection establishment is handled in the	778	sends are immediate, connection establishment is handled in the
658	background.	779	background.
659		780
660	=item * Erlang can silently lose messages, AEMP cannot.	781	=item * Erlang can silently lose messages, AEMP cannot.
661		782
…		…
664	and c, and the other side only receives messages a and c).	785	and c, and the other side only receives messages a and c).
665		786
666	AEMP guarantees correct ordering, and the guarantee that there are no	787	AEMP guarantees correct ordering, and the guarantee that there are no
667	holes in the message sequence.	788	holes in the message sequence.
668		789
669	=item * In erlang, processes can be declared dead and later be found to be	790	=item * In Erlang, processes can be declared dead and later be found to be
670	alive.	791	alive.
671		792
672	In erlang it can happen that a monitored process is declared dead and	793	In Erlang it can happen that a monitored process is declared dead and
673	linked processes get killed, but later it turns out that the process is	794	linked processes get killed, but later it turns out that the process is
674	still alive - and can receive messages.	795	still alive - and can receive messages.
675		796
676	In AEMP, when port monitoring detects a port as dead, then that port will	797	In AEMP, when port monitoring detects a port as dead, then that port will
677	eventually be killed - it cannot happen that a node detects a port as dead	798	eventually be killed - it cannot happen that a node detects a port as dead
678	and then later sends messages to it, finding it is still alive.	799	and then later sends messages to it, finding it is still alive.
679		800
680	=item * Erlang can send messages to the wrong port, AEMP does not.	801	=item * Erlang can send messages to the wrong port, AEMP does not.
681		802
682	In erlang it is quite possible that a node that restarts reuses a process	803	In Erlang it is quite possible that a node that restarts reuses a process
683	ID known to other nodes for a completely different process, causing	804	ID known to other nodes for a completely different process, causing
684	messages destined for that process to end up in an unrelated process.	805	messages destined for that process to end up in an unrelated process.
685		806
686	AEMP never reuses port IDs, so old messages or old port IDs floating	807	AEMP never reuses port IDs, so old messages or old port IDs floating
687	around in the network will not be sent to an unrelated port.	808	around in the network will not be sent to an unrelated port.
…		…
693	securely authenticate nodes.	814	securely authenticate nodes.
694		815
695	=item * The AEMP protocol is optimised for both text-based and binary	816	=item * The AEMP protocol is optimised for both text-based and binary
696	communications.	817	communications.
697		818
698	The AEMP protocol, unlike the erlang protocol, supports both	819	The AEMP protocol, unlike the Erlang protocol, supports both
699	language-independent text-only protocols (good for debugging) and binary,	820	language-independent text-only protocols (good for debugging) and binary,
700	language-specific serialisers (e.g. Storable).	821	language-specific serialisers (e.g. Storable).
701		822
702	It has also been carefully designed to be implementable in other languages	823	It has also been carefully designed to be implementable in other languages
703	with a minimum of work while gracefully degrading fucntionality to make the	824	with a minimum of work while gracefully degrading fucntionality to make the
704	protocol simple.	825	protocol simple.
705		826
		827	=item * AEMP has more flexible monitoring options than Erlang.
		828
		829	In Erlang, you can chose to receive I<all> exit signals as messages
		830	or I<none>, there is no in-between, so monitoring single processes is
		831	difficult to implement. Monitoring in AEMP is more flexible than in
		832	Erlang, as one can choose between automatic kill, exit message or callback
		833	on a per-process basis.
		834
		835	=item * Erlang tries to hide remote/local connections, AEMP does not.
		836
		837	Monitoring in Erlang is not an indicator of process death/crashes,
		838	as linking is (except linking is unreliable in Erlang).
		839
		840	In AEMP, you don't "look up" registered port names or send to named ports
		841	that might or might not be persistent. Instead, you normally spawn a port
		842	on the remote node. The init function monitors the you, and you monitor
		843	the remote port. Since both monitors are local to the node, they are much
		844	more reliable.
		845
		846	This also saves round-trips and avoids sending messages to the wrong port
		847	(hard to do in Erlang).
		848
706	=back	849	=back
707		850
708	=head1 SEE ALSO	851	=head1 SEE ALSO
709		852
710	L<AnyEvent>.	853	L<AnyEvent>.

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.34 by root, Wed Aug 5 23:50:46 2009 UTC vs. Revision 1.44 by root, Wed Aug 12 21:39:58 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.34 by root, Wed Aug 5 23:50:46 2009 UTC vs.
Revision 1.44 by root, Wed Aug 12 21:39:58 2009 UTC