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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs.
Revision 1.84 by root, Tue Sep 8 01:42:14 2009 UTC

…		…
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use AnyEvent::MP;	7	use AnyEvent::MP;
8		8
9	$NODE # contains this node's noderef	9	$NODE # contains this node's node ID
10	NODE # returns this node's noderef	10	NODE # returns this node's node ID
11	NODE $port # returns the noderef of the port
12		11
13	$SELF # receiving/own port id in rcv callbacks	12	$SELF # receiving/own port id in rcv callbacks
14		13
15	# initialise the node so it can send/receive messages	14	# initialise the node so it can send/receive messages
16	configure;	15	configure;
17		16
18	# ports are message endpoints	17	# ports are message destinations
19		18
20	# sending messages	19	# sending messages
21	snd $port, type => data...;	20	snd $port, type => data...;
22	snd $port, @msg;	21	snd $port, @msg;
23	snd @msg_with_first_element_being_a_port;	22	snd @msg_with_first_element_being_a_port;
…		…
40		39
41	=head1 CURRENT STATUS	40	=head1 CURRENT STATUS
42		41
43	bin/aemp - stable.	42	bin/aemp - stable.
44	AnyEvent::MP - stable API, should work.	43	AnyEvent::MP - stable API, should work.
45	AnyEvent::MP::Intro - uptodate, but incomplete.	44	AnyEvent::MP::Intro - explains most concepts.
46	AnyEvent::MP::Kernel - mostly stable.	45	AnyEvent::MP::Kernel - mostly stable.
47	AnyEvent::MP::Global - stable API, protocol not yet final.	46	AnyEvent::MP::Global - stable but incomplete, protocol not yet final.
48		47
49	stay tuned.	48	stay tuned.
50		49
51	=head1 DESCRIPTION	50	=head1 DESCRIPTION
52		51
53	This module (-family) implements a simple message passing framework.	52	This module (-family) implements a simple message passing framework.
54		53
…		…
56	on the same or other hosts, and you can supervise entities remotely.	55	on the same or other hosts, and you can supervise entities remotely.
57		56
58	For an introduction to this module family, see the L<AnyEvent::MP::Intro>	57	For an introduction to this module family, see the L<AnyEvent::MP::Intro>
59	manual page and the examples under F<eg/>.	58	manual page and the examples under F<eg/>.
60		59
61	At the moment, this module family is a bit underdocumented.
62
63	=head1 CONCEPTS	60	=head1 CONCEPTS
64		61
65	=over 4	62	=over 4
66		63
67	=item port	64	=item port
68		65
69	A port is something you can send messages to (with the C<snd> function).	66	Not to be confused with a TCP port, a "port" is something you can send
		67	messages to (with the C<snd> function).
70		68
71	Ports allow you to register C<rcv> handlers that can match all or just	69	Ports allow you to register C<rcv> handlers that can match all or just
72	some messages. Messages send to ports will not be queued, regardless of	70	some messages. Messages send to ports will not be queued, regardless of
73	anything was listening for them or not.	71	anything was listening for them or not.
74		72
…		…
85		83
86	Nodes are either public (have one or more listening ports) or private	84	Nodes are either public (have one or more listening ports) or private
87	(no listening ports). Private nodes cannot talk to other private nodes	85	(no listening ports). Private nodes cannot talk to other private nodes
88	currently.	86	currently.
89		87
90	=item node ID - C<[a-za-Z0-9_\-.:]+>	88	=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
91		89
92	A node ID is a string that uniquely identifies the node within a	90	A node ID is a string that uniquely identifies the node within a
93	network. Depending on the configuration used, node IDs can look like a	91	network. Depending on the configuration used, node IDs can look like a
94	hostname, a hostname and a port, or a random string. AnyEvent::MP itself	92	hostname, a hostname and a port, or a random string. AnyEvent::MP itself
95	doesn't interpret node IDs in any way.	93	doesn't interpret node IDs in any way.
…		…
99	Nodes can only talk to each other by creating some kind of connection to	97	Nodes can only talk to each other by creating some kind of connection to
100	each other. To do this, nodes should listen on one or more local transport	98	each other. To do this, nodes should listen on one or more local transport
101	endpoints - binds. Currently, only standard C<ip:port> specifications can	99	endpoints - binds. Currently, only standard C<ip:port> specifications can
102	be used, which specify TCP ports to listen on.	100	be used, which specify TCP ports to listen on.
103		101
104	=item seeds - C<host:port>	102	=item seed nodes
105		103
106	When a node starts, it knows nothing about the network. To teach the node	104	When a node starts, it knows nothing about the network. To teach the node
107	about the network it first has to contact some other node within the	105	about the network it first has to contact some other node within the
108	network. This node is called a seed.	106	network. This node is called a seed.
109		107
110	Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes	108	Apart from the fact that other nodes know them as seed nodes and they have
		109	to have fixed listening addresses, seed nodes are perfectly normal nodes -
		110	any node can function as a seed node for others.
		111
		112	In addition to discovering the network, seed nodes are also used to
		113	maintain the network and to connect nodes that otherwise would have
		114	trouble connecting. They form the backbone of the AnyEvent::MP network.
		115
111	are expected to be long-running, and at least one of those should always	116	Seed nodes are expected to be long-running, and at least one seed node
112	be available. When nodes run out of connections (e.g. due to a network	117	should always be available.
113	error), they try to re-establish connections to some seednodes again to
114	join the network.
115		118
116	Apart from being sued for seeding, seednodes are not special in any way -	119	=item seeds - C<host:port>
117	every public node can be a seednode.	120
		121	Seeds are transport endpoint(s) (usually a hostname/IP address and a
		122	TCP port) of nodes thta should be used as seed nodes.
		123
		124	The nodes listening on those endpoints are expected to be long-running,
		125	and at least one of those should always be available. When nodes run out
		126	of connections (e.g. due to a network error), they try to re-establish
		127	connections to some seednodes again to join the network.
118		128
119	=back	129	=back
120		130
121	=head1 VARIABLES/FUNCTIONS	131	=head1 VARIABLES/FUNCTIONS
122		132
…		…
161		171
162	=item $nodeid = node_of $port	172	=item $nodeid = node_of $port
163		173
164	Extracts and returns the node ID from a port ID or a node ID.	174	Extracts and returns the node ID from a port ID or a node ID.
165		175
		176	=item configure $profile, key => value...
		177
166	=item configure key => value...	178	=item configure key => value...
167		179
168	Before a node can talk to other nodes on the network (i.e. enter	180	Before a node can talk to other nodes on the network (i.e. enter
169	"distributed mode") it has to configure itself - the minimum a node needs	181	"distributed mode") it has to configure itself - the minimum a node needs
170	to know is its own name, and optionally it should know the addresses of	182	to know is its own name, and optionally it should know the addresses of
…		…
177		189
178	=item step 1, gathering configuration from profiles	190	=item step 1, gathering configuration from profiles
179		191
180	The function first looks up a profile in the aemp configuration (see the	192	The function first looks up a profile in the aemp configuration (see the
181	L<aemp> commandline utility). The profile name can be specified via the	193	L<aemp> commandline utility). The profile name can be specified via the
182	named C<profile> parameter. If it is missing, then the nodename (F<uname	194	named C<profile> parameter or can simply be the first parameter). If it is
183	-n>) will be used as profile name.	195	missing, then the nodename (F<uname -n>) will be used as profile name.
184		196
185	The profile data is then gathered as follows:	197	The profile data is then gathered as follows:
186		198
187	First, all remaining key => value pairs (all of which are conviniently	199	First, all remaining key => value pairs (all of which are conveniently
188	undocumented at the moment) will be interpreted as configuration	200	undocumented at the moment) will be interpreted as configuration
189	data. Then they will be overwritten by any values specified in the global	201	data. Then they will be overwritten by any values specified in the global
190	default configuration (see the F<aemp> utility), then the chain of	202	default configuration (see the F<aemp> utility), then the chain of
191	profiles chosen by the profile name (and any C<parent> attributes).	203	profiles chosen by the profile name (and any C<parent> attributes).
192		204
…		…
372		384
373	=cut	385	=cut
374		386
375	sub rcv($@) {	387	sub rcv($@) {
376	my $port = shift;	388	my $port = shift;
377	my ($noderef, $portid) = split /#/, $port, 2;	389	my ($nodeid, $portid) = split /#/, $port, 2;
378		390
379	$NODE{$noderef} == $NODE{""}	391	$NODE{$nodeid} == $NODE{""}
380	or Carp::croak "$port: rcv can only be called on local ports, caught";	392	or Carp::croak "$port: rcv can only be called on local ports, caught";
381		393
382	while (@_) {	394	while (@_) {
383	if (ref $_[0]) {	395	if (ref $_[0]) {
384	if (my $self = $PORT_DATA{$portid}) {	396	if (my $self = $PORT_DATA{$portid}) {
…		…
475		487
476	Monitor the given port and do something when the port is killed or	488	Monitor the given port and do something when the port is killed or
477	messages to it were lost, and optionally return a guard that can be used	489	messages to it were lost, and optionally return a guard that can be used
478	to stop monitoring again.	490	to stop monitoring again.
479		491
		492	In the first form (callback), the callback is simply called with any
		493	number of C<@reason> elements (no @reason means that the port was deleted
		494	"normally"). Note also that I<< the callback B<must> never die >>, so use
		495	C<eval> if unsure.
		496
		497	In the second form (another port given), the other port (C<$rcvport>)
		498	will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
		499	"normal" kils nothing happens, while under all other conditions, the other
		500	port is killed with the same reason.
		501
		502	The third form (kill self) is the same as the second form, except that
		503	C<$rvport> defaults to C<$SELF>.
		504
		505	In the last form (message), a message of the form C<@msg, @reason> will be
		506	C<snd>.
		507
		508	Monitoring-actions are one-shot: once messages are lost (and a monitoring
		509	alert was raised), they are removed and will not trigger again.
		510
		511	As a rule of thumb, monitoring requests should always monitor a port from
		512	a local port (or callback). The reason is that kill messages might get
		513	lost, just like any other message. Another less obvious reason is that
		514	even monitoring requests can get lost (for example, when the connection
		515	to the other node goes down permanently). When monitoring a port locally
		516	these problems do not exist.
		517
480	C<mon> effectively guarantees that, in the absence of hardware failures,	518	C<mon> effectively guarantees that, in the absence of hardware failures,
481	after starting the monitor, either all messages sent to the port will	519	after starting the monitor, either all messages sent to the port will
482	arrive, or the monitoring action will be invoked after possible message	520	arrive, or the monitoring action will be invoked after possible message
483	loss has been detected. No messages will be lost "in between" (after	521	loss has been detected. No messages will be lost "in between" (after
484	the first lost message no further messages will be received by the	522	the first lost message no further messages will be received by the
485	port). After the monitoring action was invoked, further messages might get	523	port). After the monitoring action was invoked, further messages might get
486	delivered again.	524	delivered again.
487		525
488	Note that monitoring-actions are one-shot: once messages are lost (and a	526	Inter-host-connection timeouts and monitoring depend on the transport
489	monitoring alert was raised), they are removed and will not trigger again.	527	used. The only transport currently implemented is TCP, and AnyEvent::MP
		528	relies on TCP to detect node-downs (this can take 10-15 minutes on a
		529	non-idle connection, and usually around two hours for idle conenctions).
490		530
491	In the first form (callback), the callback is simply called with any	531	This means that monitoring is good for program errors and cleaning up
492	number of C<@reason> elements (no @reason means that the port was deleted	532	stuff eventually, but they are no replacement for a timeout when you need
493	"normally"). Note also that I<< the callback B<must> never die >>, so use	533	to ensure some maximum latency.
494	C<eval> if unsure.
495
496	In the second form (another port given), the other port (C<$rcvport>)
497	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
498	"normal" kils nothing happens, while under all other conditions, the other
499	port is killed with the same reason.
500
501	The third form (kill self) is the same as the second form, except that
502	C<$rvport> defaults to C<$SELF>.
503
504	In the last form (message), a message of the form C<@msg, @reason> will be
505	C<snd>.
506
507	As a rule of thumb, monitoring requests should always monitor a port from
508	a local port (or callback). The reason is that kill messages might get
509	lost, just like any other message. Another less obvious reason is that
510	even monitoring requests can get lost (for exmaple, when the connection
511	to the other node goes down permanently). When monitoring a port locally
512	these problems do not exist.
513		534
514	Example: call a given callback when C<$port> is killed.	535	Example: call a given callback when C<$port> is killed.
515		536
516	mon $port, sub { warn "port died because of <@_>\n" };	537	mon $port, sub { warn "port died because of <@_>\n" };
517		538
…		…
524	mon $port, $self => "restart";	545	mon $port, $self => "restart";
525		546
526	=cut	547	=cut
527		548
528	sub mon {	549	sub mon {
529	my ($noderef, $port) = split /#/, shift, 2;	550	my ($nodeid, $port) = split /#/, shift, 2;
530		551
531	my $node = $NODE{$noderef} \|\| add_node $noderef;	552	my $node = $NODE{$nodeid} \|\| add_node $nodeid;
532		553
533	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';	554	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
534		555
535	unless (ref $cb) {	556	unless (ref $cb) {
536	if (@_) {	557	if (@_) {
…		…
612	the package, then the package above the package and so on (e.g.	633	the package, then the package above the package and so on (e.g.
613	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function	634	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
614	exists or it runs out of package names.	635	exists or it runs out of package names.
615		636
616	The init function is then called with the newly-created port as context	637	The init function is then called with the newly-created port as context
617	object (C<$SELF>) and the C<@initdata> values as arguments.	638	object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
		639	call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
		640	the port might not get created.
618		641
619	A common idiom is to pass a local port, immediately monitor the spawned	642	A common idiom is to pass a local port, immediately monitor the spawned
620	port, and in the remote init function, immediately monitor the passed	643	port, and in the remote init function, immediately monitor the passed
621	local port. This two-way monitoring ensures that both ports get cleaned up	644	local port. This two-way monitoring ensures that both ports get cleaned up
622	when there is a problem.	645	when there is a problem.
623		646
		647	C<spawn> guarantees that the C<$initfunc> has no visible effects on the
		648	caller before C<spawn> returns (by delaying invocation when spawn is
		649	called for the local node).
		650
624	Example: spawn a chat server port on C<$othernode>.	651	Example: spawn a chat server port on C<$othernode>.
625		652
626	# this node, executed from within a port context:	653	# this node, executed from within a port context:
627	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;	654	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
628	mon $server;	655	mon $server;
…		…
642		669
643	sub _spawn {	670	sub _spawn {
644	my $port = shift;	671	my $port = shift;
645	my $init = shift;	672	my $init = shift;
646		673
		674	# rcv will create the actual port
647	local $SELF = "$NODE#$port";	675	local $SELF = "$NODE#$port";
648	eval {	676	eval {
649	&{ load_func $init }	677	&{ load_func $init }
650	};	678	};
651	_self_die if $@;	679	_self_die if $@;
652	}	680	}
653		681
654	sub spawn(@) {	682	sub spawn(@) {
655	my ($noderef, undef) = split /#/, shift, 2;	683	my ($nodeid, undef) = split /#/, shift, 2;
656		684
657	my $id = "$RUNIQ." . $ID++;	685	my $id = "$RUNIQ." . $ID++;
658		686
659	$_[0] =~ /::/	687	$_[0] =~ /::/
660	or Carp::croak "spawn init function must be a fully-qualified name, caught";	688	or Carp::croak "spawn init function must be a fully-qualified name, caught";
661		689
662	snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;	690	snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
663		691
664	"$noderef#$id"	692	"$nodeid#$id"
665	}	693	}
666		694
667	=item after $timeout, @msg	695	=item after $timeout, @msg
668		696
669	=item after $timeout, $callback	697	=item after $timeout, $callback
…		…
708		736
709	=item * Node IDs are arbitrary strings in AEMP.	737	=item * Node IDs are arbitrary strings in AEMP.
710		738
711	Erlang relies on special naming and DNS to work everywhere in the same	739	Erlang relies on special naming and DNS to work everywhere in the same
712	way. AEMP relies on each node somehow knowing its own address(es) (e.g. by	740	way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
713	configuraiton or DNS), but will otherwise discover other odes itself.	741	configuration or DNS), but will otherwise discover other odes itself.
714		742
715	=item * Erlang has a "remote ports are like local ports" philosophy, AEMP	743	=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
716	uses "local ports are like remote ports".	744	uses "local ports are like remote ports".
717		745
718	The failure modes for local ports are quite different (runtime errors	746	The failure modes for local ports are quite different (runtime errors
…		…
731		759
732	Erlang uses processes that selectively receive messages, and therefore	760	Erlang uses processes that selectively receive messages, and therefore
733	needs a queue. AEMP is event based, queuing messages would serve no	761	needs a queue. AEMP is event based, queuing messages would serve no
734	useful purpose. For the same reason the pattern-matching abilities of	762	useful purpose. For the same reason the pattern-matching abilities of
735	AnyEvent::MP are more limited, as there is little need to be able to	763	AnyEvent::MP are more limited, as there is little need to be able to
736	filter messages without dequeing them.	764	filter messages without dequeuing them.
737		765
738	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).	766	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
739		767
740	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	768	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
741		769
…		…
847	L<AnyEvent::MP::Kernel> - more, lower-level, stuff.	875	L<AnyEvent::MP::Kernel> - more, lower-level, stuff.
848		876
849	L<AnyEvent::MP::Global> - network maintainance and port groups, to find	877	L<AnyEvent::MP::Global> - network maintainance and port groups, to find
850	your applications.	878	your applications.
851		879
		880	L<AnyEvent::MP::LogCatcher> - simple service to display log messages from
		881	all nodes.
		882
852	L<AnyEvent>.	883	L<AnyEvent>.
853		884
854	=head1 AUTHOR	885	=head1 AUTHOR
855		886
856	Marc Lehmann <schmorp@schmorp.de>	887	Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs. Revision 1.84 by root, Tue Sep 8 01:42:14 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.74 by root, Mon Aug 31 11:11:27 2009 UTC vs.
Revision 1.84 by root, Tue Sep 8 01:42:14 2009 UTC