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