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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC vs.
Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC

…		…
22	snd $port2, ping => $port1;	22	snd $port2, ping => $port1;
23		23
24	# more, smarter, matches (_any_ is exported by this module)	24	# more, smarter, matches (_any_ is exported by this module)
25	rcv $port, [child_died => $pid] => sub { ...	25	rcv $port, [child_died => $pid] => sub { ...
26	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3	26	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
		27
		28	# monitoring
		29	mon $port, $cb->(@msg) # callback is invoked on death
		30	mon $port, $otherport # kill otherport on abnormal death
		31	mon $port, $otherport, @msg # send message on death
27		32
28	=head1 DESCRIPTION	33	=head1 DESCRIPTION
29		34
30	This module (-family) implements a simple message passing framework.	35	This module (-family) implements a simple message passing framework.
31		36
…		…
127		132
128	=item $noderef = node_of $port	133	=item $noderef = node_of $port
129		134
130	Extracts and returns the noderef from a portid or a noderef.	135	Extracts and returns the noderef from a portid or a noderef.
131		136
		137	=item initialise_node $noderef, $seednode, $seednode...
		138
		139	=item initialise_node "slave/", $master, $master...
		140
		141	Before a node can talk to other nodes on the network it has to initialise
		142	itself - the minimum a node needs to know is it's own name, and optionally
		143	it should know the noderefs of some other nodes in the network.
		144
		145	This function initialises a node - it must be called exactly once (or
		146	never) before calling other AnyEvent::MP functions.
		147
		148	All arguments are noderefs, which can be either resolved or unresolved.
		149
		150	There are two types of networked nodes, public nodes and slave nodes:
		151
		152	=over 4
		153
		154	=item public nodes
		155
		156	For public nodes, C<$noderef> must either be a (possibly unresolved)
		157	noderef, in which case it will be resolved, or C<undef> (or missing), in
		158	which case the noderef will be guessed.
		159
		160	Afterwards, the node will bind itself on all endpoints and try to connect
		161	to all additional C<$seednodes> that are specified. Seednodes are optional
		162	and can be used to quickly bootstrap the node into an existing network.
		163
		164	=item slave nodes
		165
		166	When the C<$noderef> is the special string C<slave/>, then the node will
		167	become a slave node. Slave nodes cannot be contacted from outside and will
		168	route most of their traffic to the master node that they attach to.
		169
		170	At least one additional noderef is required: The node will try to connect
		171	to all of them and will become a slave attached to the first node it can
		172	successfully connect to.
		173
		174	=back
		175
		176	This function will block until all nodes have been resolved and, for slave
		177	nodes, until it has successfully established a connection to a master
		178	server.
		179
		180	Example: become a public node listening on the default node.
		181
		182	initialise_node;
		183
		184	Example: become a public node, and try to contact some well-known master
		185	servers to become part of the network.
		186
		187	initialise_node undef, "master1", "master2";
		188
		189	Example: become a public node listening on port C<4041>.
		190
		191	initialise_node 4041;
		192
		193	Example: become a public node, only visible on localhost port 4044.
		194
		195	initialise_node "locahost:4044";
		196
		197	Example: become a slave node to any of the specified master servers.
		198
		199	initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
		200
132	=item $cv = resolve_node $noderef	201	=item $cv = resolve_node $noderef
133		202
134	Takes an unresolved node reference that may contain hostnames and	203	Takes an unresolved node reference that may contain hostnames and
135	abbreviated IDs, resolves all of them and returns a resolved node	204	abbreviated IDs, resolves all of them and returns a resolved node
136	reference.	205	reference.
…		…
233	$port	302	$port
234	}	303	}
235		304
236	=item reg $port, $name	305	=item reg $port, $name
237		306
238	Registers the given port under the name C<$name>. If the name already	307	=item reg $name
239	exists it is replaced.	308
		309	Registers the given port (or C<$SELF><<< if missing) under the name
		310	C<$name>. If the name already exists it is replaced.
240		311
241	A port can only be registered under one well known name.	312	A port can only be registered under one well known name.
242		313
243	A port automatically becomes unregistered when it is killed.	314	A port automatically becomes unregistered when it is killed.
244		315
245	=cut	316	=cut
246		317
247	sub reg(@) {	318	sub reg(@) {
248	my ($port, $name) = @_;	319	my $port = @_ > 1 ? shift : $SELF \|\| Carp::croak 'reg: called with one argument only, but $SELF not set,';
249		320
250	$REG{$name} = $port;	321	$REG{$_[0]} = $port;
251	}	322	}
252		323
253	=item rcv $port, $callback->(@msg)	324	=item rcv $port, $callback->(@msg)
254		325
255	Replaces the callback on the specified miniport (after converting it to	326	Replaces the callback on the specified miniport (after converting it to
…		…
260	=item rcv $port, $smartmatch => $callback->(@msg), ...	331	=item rcv $port, $smartmatch => $callback->(@msg), ...
261		332
262	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...	333	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...
263		334
264	Register callbacks to be called on matching messages on the given full	335	Register callbacks to be called on matching messages on the given full
265	port (after converting it to one if required).	336	port (after converting it to one if required) and return the port.
266		337
267	The callback has to return a true value when its work is done, after	338	The callback has to return a true value when its work is done, after
268	which is will be removed, or a false value in which case it will stay	339	which is will be removed, or a false value in which case it will stay
269	registered.	340	registered.
270		341
…		…
282	exported by this module) matches any single element of the message.	353	exported by this module) matches any single element of the message.
283		354
284	While not required, it is highly recommended that the first matching	355	While not required, it is highly recommended that the first matching
285	element is a string identifying the message. The one-string-only match is	356	element is a string identifying the message. The one-string-only match is
286	also the most efficient match (by far).	357	also the most efficient match (by far).
		358
		359	Example: create a port and bind receivers on it in one go.
		360
		361	my $port = rcv port,
		362	msg1 => sub { ...; 0 },
		363	msg2 => sub { ...; 0 },
		364	;
		365
		366	Example: create a port, bind receivers and send it in a message elsewhere
		367	in one go:
		368
		369	snd $otherport, reply =>
		370	rcv port,
		371	msg1 => sub { ...; 0 },
		372	...
		373	;
287		374
288	=cut	375	=cut
289		376
290	sub rcv($@) {	377	sub rcv($@) {
291	my $port = shift;	378	my $port = shift;
…		…
398	}	485	}
399	}	486	}
400		487
401	=item $guard = mon $port, $cb->(@reason)	488	=item $guard = mon $port, $cb->(@reason)
402		489
403	=item $guard = mon $port, $otherport	490	=item $guard = mon $port, $rcvport
404		491
		492	=item $guard = mon $port
		493
405	=item $guard = mon $port, $otherport, @msg	494	=item $guard = mon $port, $rcvport, @msg
406		495
407	Monitor the given port and do something when the port is killed.	496	Monitor the given port and do something when the port is killed, and
		497	optionally return a guard that can be used to stop monitoring again.
408		498
409	In the first form, the callback is simply called with any number	499	In the first form (callback), the callback is simply called with any
410	of C<@reason> elements (no @reason means that the port was deleted	500	number of C<@reason> elements (no @reason means that the port was deleted
411	"normally"). Note also that I<< the callback B<must> never die >>, so use	501	"normally"). Note also that I<< the callback B<must> never die >>, so use
412	C<eval> if unsure.	502	C<eval> if unsure.
413		503
414	In the second form, the other port will be C<kil>'ed with C<@reason>, iff	504	In the second form (another port given), the other port (C<$rcvport)
415	a @reason was specified, i.e. on "normal" kils nothing happens, while	505	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
416	under all other conditions, the other port is killed with the same reason.	506	"normal" kils nothing happens, while under all other conditions, the other
		507	port is killed with the same reason.
417		508
		509	The third form (kill self) is the same as the second form, except that
		510	C<$rvport> defaults to C<$SELF>.
		511
418	In the last form, a message of the form C<@msg, @reason> will be C<snd>.	512	In the last form (message), a message of the form C<@msg, @reason> will be
		513	C<snd>.
		514
		515	As a rule of thumb, monitoring requests should always monitor a port from
		516	a local port (or callback). The reason is that kill messages might get
		517	lost, just like any other message. Another less obvious reason is that
		518	even monitoring requests can get lost (for exmaple, when the connection
		519	to the other node goes down permanently). When monitoring a port locally
		520	these problems do not exist.
419		521
420	Example: call a given callback when C<$port> is killed.	522	Example: call a given callback when C<$port> is killed.
421		523
422	mon $port, sub { warn "port died because of <@_>\n" };	524	mon $port, sub { warn "port died because of <@_>\n" };
423		525
424	Example: kill ourselves when C<$port> is killed abnormally.	526	Example: kill ourselves when C<$port> is killed abnormally.
425		527
426	mon $port, $self;	528	mon $port;
427		529
428	Example: send us a restart message another C<$port> is killed.	530	Example: send us a restart message when another C<$port> is killed.
429		531
430	mon $port, $self => "restart";	532	mon $port, $self => "restart";
431		533
432	=cut	534	=cut
433		535
434	sub mon {	536	sub mon {
435	my ($noderef, $port) = split /#/, shift, 2;	537	my ($noderef, $port) = split /#/, shift, 2;
436		538
437	my $node = $NODE{$noderef} \|\| add_node $noderef;	539	my $node = $NODE{$noderef} \|\| add_node $noderef;
438		540
439	my $cb = shift;	541	my $cb = @_ ? $_[0] : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
440		542
441	unless (ref $cb) {	543	unless (ref $cb) {
442	if (@_) {	544	if (@_) {
443	# send a kill info message	545	# send a kill info message
444	my (@msg) = ($cb, @_);	546	my (@msg) = @_;
445	$cb = sub { snd @msg, @_ };	547	$cb = sub { snd @msg, @_ };
446	} else {	548	} else {
447	# simply kill other port	549	# simply kill other port
448	my $port = $cb;	550	my $port = $cb;
449	$cb = sub { kil $port, @_ if @_ };	551	$cb = sub { kil $port, @_ if @_ };
…		…
475	=cut	577	=cut
476		578
477	sub mon_guard {	579	sub mon_guard {
478	my ($port, @refs) = @_;	580	my ($port, @refs) = @_;
479		581
		582	#TODO: mon-less form?
		583
480	mon $port, sub { 0 && @refs }	584	mon $port, sub { 0 && @refs }
481	}	585	}
482		586
483	=item lnk $port1, $port2
484
485	Link two ports. This is simply a shorthand for:
486
487	mon $port1, $port2;
488	mon $port2, $port1;
489
490	It means that if either one is killed abnormally, the other one gets
491	killed as well.
492
493	=item kil $port[, @reason]	587	=item kil $port[, @reason]
494		588
495	Kill the specified port with the given C<@reason>.	589	Kill the specified port with the given C<@reason>.
496		590
497	If no C<@reason> is specified, then the port is killed "normally" (linked	591	If no C<@reason> is specified, then the port is killed "normally" (linked
…		…
503	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks	597	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
504	will be reported as reason C<< die => $@ >>.	598	will be reported as reason C<< die => $@ >>.
505		599
506	Transport/communication errors are reported as C<< transport_error =>	600	Transport/communication errors are reported as C<< transport_error =>
507	$message >>.	601	$message >>.
508
509	=back
510
511	=head1 FUNCTIONS FOR NODES
512
513	=over 4
514
515	=item initialise_node $noderef, $seednode, $seednode...
516
517	=item initialise_node "slave/", $master, $master...
518
519	Initialises a node - must be called exactly once before calling other
520	AnyEvent::MP functions when talking to other nodes is required.
521
522	All arguments are noderefs, which can be either resolved or unresolved.
523
524	There are two types of networked nodes, public nodes and slave nodes:
525
526	=over 4
527
528	=item public nodes
529
530	For public nodes, C<$noderef> must either be a (possibly unresolved)
531	noderef, in which case it will be resolved, or C<undef> (or missing), in
532	which case the noderef will be guessed.
533
534	Afterwards, the node will bind itself on all endpoints and try to connect
535	to all additional C<$seednodes> that are specified. Seednodes are optional
536	and can be used to quickly bootstrap the node into an existing network.
537
538	=item slave nodes
539
540	When the C<$noderef> is the special string C<slave/>, then the node will
541	become a slave node. Slave nodes cannot be contacted from outside and will
542	route most of their traffic to the master node that they attach to.
543
544	At least one additional noderef is required: The node will try to connect
545	to all of them and will become a slave attached to the first node it can
546	successfully connect to.
547
548	=back
549
550	This function will block until all nodes have been resolved and, for slave
551	nodes, until it has successfully established a connection to a master
552	server.
553
554	Example: become a public node listening on the default node.
555
556	initialise_node;
557
558	Example: become a public node, and try to contact some well-known master
559	servers to become part of the network.
560
561	initialise_node undef, "master1", "master2";
562
563	Example: become a public node listening on port C<4041>.
564
565	initialise_node 4041;
566
567	Example: become a public node, only visible on localhost port 4044.
568
569	initialise_node "locahost:4044";
570
571	Example: become a slave node to any of the specified master servers.
572
573	initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
574
575	=cut
576		602
577	=back	603	=back
578		604
579	=head1 NODE MESSAGES	605	=head1 NODE MESSAGES
580		606
…		…
622		648
623	=back	649	=back
624		650
625	=head1 AnyEvent::MP vs. Distributed Erlang	651	=head1 AnyEvent::MP vs. Distributed Erlang
626		652
627	AnyEvent::MP got lots of its ideas from distributed erlang (erlang node	653	AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
628	== aemp node, erlang process == aemp port), so many of the documents and	654	== aemp node, Erlang process == aemp port), so many of the documents and
629	programming techniques employed by erlang apply to AnyEvent::MP. Here is a	655	programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
630	sample:	656	sample:
631		657
632	http://www.erlang.se/doc/programming_rules.shtml	658	http://www.Erlang.se/doc/programming_rules.shtml
633	http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4	659	http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
634	http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6	660	http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6
635	http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5	661	http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
636		662
637	Despite the similarities, there are also some important differences:	663	Despite the similarities, there are also some important differences:
638		664
639	=over 4	665	=over 4
640		666
…		…
651		677
652	Erlang uses processes that selctively receive messages, and therefore	678	Erlang uses processes that selctively receive messages, and therefore
653	needs a queue. AEMP is event based, queuing messages would serve no useful	679	needs a queue. AEMP is event based, queuing messages would serve no useful
654	purpose.	680	purpose.
655		681
656	(But see L<Coro::MP> for a more erlang-like process model on top of AEMP).	682	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
657		683
658	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	684	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
659		685
660	Sending messages in erlang is synchronous and blocks the process. AEMP	686	Sending messages in Erlang is synchronous and blocks the process. AEMP
661	sends are immediate, connection establishment is handled in the	687	sends are immediate, connection establishment is handled in the
662	background.	688	background.
663		689
664	=item * Erlang can silently lose messages, AEMP cannot.	690	=item * Erlang can silently lose messages, AEMP cannot.
665		691
…		…
668	and c, and the other side only receives messages a and c).	694	and c, and the other side only receives messages a and c).
669		695
670	AEMP guarantees correct ordering, and the guarantee that there are no	696	AEMP guarantees correct ordering, and the guarantee that there are no
671	holes in the message sequence.	697	holes in the message sequence.
672		698
673	=item * In erlang, processes can be declared dead and later be found to be	699	=item * In Erlang, processes can be declared dead and later be found to be
674	alive.	700	alive.
675		701
676	In erlang it can happen that a monitored process is declared dead and	702	In Erlang it can happen that a monitored process is declared dead and
677	linked processes get killed, but later it turns out that the process is	703	linked processes get killed, but later it turns out that the process is
678	still alive - and can receive messages.	704	still alive - and can receive messages.
679		705
680	In AEMP, when port monitoring detects a port as dead, then that port will	706	In AEMP, when port monitoring detects a port as dead, then that port will
681	eventually be killed - it cannot happen that a node detects a port as dead	707	eventually be killed - it cannot happen that a node detects a port as dead
682	and then later sends messages to it, finding it is still alive.	708	and then later sends messages to it, finding it is still alive.
683		709
684	=item * Erlang can send messages to the wrong port, AEMP does not.	710	=item * Erlang can send messages to the wrong port, AEMP does not.
685		711
686	In erlang it is quite possible that a node that restarts reuses a process	712	In Erlang it is quite possible that a node that restarts reuses a process
687	ID known to other nodes for a completely different process, causing	713	ID known to other nodes for a completely different process, causing
688	messages destined for that process to end up in an unrelated process.	714	messages destined for that process to end up in an unrelated process.
689		715
690	AEMP never reuses port IDs, so old messages or old port IDs floating	716	AEMP never reuses port IDs, so old messages or old port IDs floating
691	around in the network will not be sent to an unrelated port.	717	around in the network will not be sent to an unrelated port.
…		…
697	securely authenticate nodes.	723	securely authenticate nodes.
698		724
699	=item * The AEMP protocol is optimised for both text-based and binary	725	=item * The AEMP protocol is optimised for both text-based and binary
700	communications.	726	communications.
701		727
702	The AEMP protocol, unlike the erlang protocol, supports both	728	The AEMP protocol, unlike the Erlang protocol, supports both
703	language-independent text-only protocols (good for debugging) and binary,	729	language-independent text-only protocols (good for debugging) and binary,
704	language-specific serialisers (e.g. Storable).	730	language-specific serialisers (e.g. Storable).
705		731
706	It has also been carefully designed to be implementable in other languages	732	It has also been carefully designed to be implementable in other languages
707	with a minimum of work while gracefully degrading fucntionality to make the	733	with a minimum of work while gracefully degrading fucntionality to make the
708	protocol simple.	734	protocol simple.
709		735
		736	=item * AEMP has more flexible monitoring options than Erlang.
		737
		738	In Erlang, you can chose to receive I<all> exit signals as messages
		739	or I<none>, there is no in-between, so monitoring single processes is
		740	difficult to implement. Monitoring in AEMP is more flexible than in
		741	Erlang, as one can choose between automatic kill, exit message or callback
		742	on a per-process basis.
		743
		744	=item * Erlang tries to hide remote/local connections, AEMP does not.
		745
		746	Monitoring in Erlang is not an indicator of process death/crashes,
		747	as linking is (except linking is unreliable in Erlang).
		748
		749	In AEMP, you don't "look up" registered port names or send to named ports
		750	that might or might not be persistent. Instead, you normally spawn a port
		751	on the remote node. The init function monitors the you, and you monitor
		752	the remote port. Since both monitors are local to the node, they are much
		753	more reliable.
		754
		755	This also saves round-trips and avoids sending messages to the wrong port
		756	(hard to do in Erlang).
		757
710	=back	758	=back
711		759
712	=head1 SEE ALSO	760	=head1 SEE ALSO
713		761
714	L<AnyEvent>.	762	L<AnyEvent>.

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC vs. Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC vs.
Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC