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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.68 by root, Fri Aug 28 23:06:33 2009 UTC vs.
Revision 1.78 by root, Thu Sep 3 20:16:36 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	initialise_node;	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;
24		23
25	# creating/using ports, the simple way	24	# creating/using ports, the simple way
26	my $simple_port = port { my @msg = @_; 0 };	25	my $simple_port = port { my @msg = @_ };
27		26
28	# creating/using ports, tagged message matching	27	# creating/using ports, tagged message matching
29	my $port = port;	28	my $port = port;
30	rcv $port, ping => sub { snd $_[0], "pong"; 0 };	29	rcv $port, ping => sub { snd $_[0], "pong" };
31	rcv $port, pong => sub { warn "pong received\n"; 0 };	30	rcv $port, pong => sub { warn "pong received\n" };
32		31
33	# create a port on another node	32	# create a port on another node
34	my $port = spawn $node, $initfunc, @initdata;	33	my $port = spawn $node, $initfunc, @initdata;
35		34
36	# monitoring	35	# monitoring
…		…
38	mon $port, $otherport # kill otherport on abnormal death	37	mon $port, $otherport # kill otherport on abnormal death
39	mon $port, $otherport, @msg # send message on death	38	mon $port, $otherport, @msg # send message on death
40		39
41	=head1 CURRENT STATUS	40	=head1 CURRENT STATUS
42		41
		42	bin/aemp - stable.
43	AnyEvent::MP - stable API, should work	43	AnyEvent::MP - stable API, should work.
44	AnyEvent::MP::Intro - outdated	44	AnyEvent::MP::Intro - explains most concepts.
45	AnyEvent::MP::Kernel - mostly stable	45	AnyEvent::MP::Kernel - mostly stable.
46	AnyEvent::MP::Global - mostly stable	46	AnyEvent::MP::Global - stable API, protocol not yet final.
47	AnyEvent::MP::Node - mostly stable, but internal anyways
48	AnyEvent::MP::Transport - mostly stable, but internal anyways
49		47
50	stay tuned.	48	stay tuned.
51		49
52	=head1 DESCRIPTION	50	=head1 DESCRIPTION
53		51
…		…
56	Despite its simplicity, you can securely message other processes running	54	Despite its simplicity, you can securely message other processes running
57	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.
58		56
59	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>
60	manual page and the examples under F<eg/>.	58	manual page and the examples under F<eg/>.
61
62	At the moment, this module family is a bit underdocumented.
63		59
64	=head1 CONCEPTS	60	=head1 CONCEPTS
65		61
66	=over 4	62	=over 4
67		63
…		…
139		135
140	our $VERSION = $AnyEvent::MP::Kernel::VERSION;	136	our $VERSION = $AnyEvent::MP::Kernel::VERSION;
141		137
142	our @EXPORT = qw(	138	our @EXPORT = qw(
143	NODE $NODE *SELF node_of after	139	NODE $NODE *SELF node_of after
144	initialise_node	140	configure
145	snd rcv mon mon_guard kil reg psub spawn	141	snd rcv mon mon_guard kil reg psub spawn
146	port	142	port
147	);	143	);
148		144
149	our $SELF;	145	our $SELF;
…		…
156		152
157	=item $thisnode = NODE / $NODE	153	=item $thisnode = NODE / $NODE
158		154
159	The C<NODE> function returns, and the C<$NODE> variable contains, the node	155	The C<NODE> function returns, and the C<$NODE> variable contains, the node
160	ID of the node running in the current process. This value is initialised by	156	ID of the node running in the current process. This value is initialised by
161	a call to C<initialise_node>.	157	a call to C<configure>.
162		158
163	=item $nodeid = node_of $port	159	=item $nodeid = node_of $port
164		160
165	Extracts and returns the node ID from a port ID or a node ID.	161	Extracts and returns the node ID from a port ID or a node ID.
166		162
167	=item initialise_node $profile_name	163	=item configure $profile, key => value...
		164
		165	=item configure key => value...
168		166
169	Before a node can talk to other nodes on the network (i.e. enter	167	Before a node can talk to other nodes on the network (i.e. enter
170	"distributed mode") it has to initialise itself - the minimum a node needs	168	"distributed mode") it has to configure itself - the minimum a node needs
171	to know is its own name, and optionally it should know the addresses of	169	to know is its own name, and optionally it should know the addresses of
172	some other nodes in the network to discover other nodes.	170	some other nodes in the network to discover other nodes.
173		171
174	This function initialises a node - it must be called exactly once (or	172	This function configures a node - it must be called exactly once (or
175	never) before calling other AnyEvent::MP functions.	173	never) before calling other AnyEvent::MP functions.
176		174
177	The first argument is a profile name. If it is C<undef> or missing, then	175	=over 4
178	the current nodename will be used instead (i.e. F<uname -n>).
179		176
		177	=item step 1, gathering configuration from profiles
		178
180	The function then looks up the profile in the aemp configuration (see the	179	The function first looks up a profile in the aemp configuration (see the
181	L<aemp> commandline utility).	180	L<aemp> commandline utility). The profile name can be specified via the
		181	named C<profile> parameter or can simply be the first parameter). If it is
		182	missing, then the nodename (F<uname -n>) will be used as profile name.
		183
		184	The profile data is then gathered as follows:
		185
		186	First, all remaining key => value pairs (all of which are conveniently
		187	undocumented at the moment) will be interpreted as configuration
		188	data. Then they will be overwritten by any values specified in the global
		189	default configuration (see the F<aemp> utility), then the chain of
		190	profiles chosen by the profile name (and any C<parent> attributes).
		191
		192	That means that the values specified in the profile have highest priority
		193	and the values specified directly via C<configure> have lowest priority,
		194	and can only be used to specify defaults.
182		195
183	If the profile specifies a node ID, then this will become the node ID of	196	If the profile specifies a node ID, then this will become the node ID of
184	this process. If not, then the profile name will be used as node ID. The	197	this process. If not, then the profile name will be used as node ID. The
185	special node ID of C<anon/> will be replaced by a random node ID.	198	special node ID of C<anon/> will be replaced by a random node ID.
		199
		200	=item step 2, bind listener sockets
186		201
187	The next step is to look up the binds in the profile, followed by binding	202	The next step is to look up the binds in the profile, followed by binding
188	aemp protocol listeners on all binds specified (it is possible and valid	203	aemp protocol listeners on all binds specified (it is possible and valid
189	to have no binds, meaning that the node cannot be contacted form the	204	to have no binds, meaning that the node cannot be contacted form the
190	outside. This means the node cannot talk to other nodes that also have no	205	outside. This means the node cannot talk to other nodes that also have no
191	binds, but it can still talk to all "normal" nodes).	206	binds, but it can still talk to all "normal" nodes).
192		207
193	If the profile does not specify a binds list, then the node ID will be	208	If the profile does not specify a binds list, then a default of C<*> is
194	treated as if it were of the form C<host:port>, which will be resolved and	209	used, meaning the node will bind on a dynamically-assigned port on every
195	used as binds list.	210	local IP address it finds.
196		211
		212	=item step 3, connect to seed nodes
		213
197	Lastly, the seeds list from the profile is passed to the	214	As the last step, the seeds list from the profile is passed to the
198	L<AnyEvent::MP::Global> module, which will then use it to keep	215	L<AnyEvent::MP::Global> module, which will then use it to keep
199	connectivity with at least on of those seed nodes at any point in time.	216	connectivity with at least one node at any point in time.
200		217
201	Example: become a distributed node listening on the guessed noderef, or	218	=back
202	the one specified via C<aemp> for the current node. This should be the	219
		220	Example: become a distributed node using the locla node name as profile.
203	most common form of invocation for "daemon"-type nodes.	221	This should be the most common form of invocation for "daemon"-type nodes.
204		222
205	initialise_node;	223	configure
206		224
207	Example: become an anonymous node. This form is often used for commandline	225	Example: become an anonymous node. This form is often used for commandline
208	clients.	226	clients.
209		227
210	initialise_node "anon/";	228	configure nodeid => "anon/";
211		229
212	Example: become a distributed node. If there is no profile of the given	230	Example: configure a node using a profile called seed, which si suitable
213	name, or no binds list was specified, resolve C<localhost:4044> and bind	231	for a seed node as it binds on all local addresses on a fixed port (4040,
214	on the resulting addresses.	232	customary for aemp).
215		233
216	initialise_node "localhost:4044";	234	# use the aemp commandline utility
		235	# aemp profile seed nodeid anon/ binds '*:4040'
		236
		237	# then use it
		238	configure profile => "seed";
		239
		240	# or simply use aemp from the shell again:
		241	# aemp run profile seed
		242
		243	# or provide a nicer-to-remember nodeid
		244	# aemp run profile seed nodeid "$(hostname)"
217		245
218	=item $SELF	246	=item $SELF
219		247
220	Contains the current port id while executing C<rcv> callbacks or C<psub>	248	Contains the current port id while executing C<rcv> callbacks or C<psub>
221	blocks.	249	blocks.
…		…
343		371
344	=cut	372	=cut
345		373
346	sub rcv($@) {	374	sub rcv($@) {
347	my $port = shift;	375	my $port = shift;
348	my ($noderef, $portid) = split /#/, $port, 2;	376	my ($nodeid, $portid) = split /#/, $port, 2;
349		377
350	$NODE{$noderef} == $NODE{""}	378	$NODE{$nodeid} == $NODE{""}
351	or Carp::croak "$port: rcv can only be called on local ports, caught";	379	or Carp::croak "$port: rcv can only be called on local ports, caught";
352		380
353	while (@_) {	381	while (@_) {
354	if (ref $_[0]) {	382	if (ref $_[0]) {
355	if (my $self = $PORT_DATA{$portid}) {	383	if (my $self = $PORT_DATA{$portid}) {
…		…
463	number of C<@reason> elements (no @reason means that the port was deleted	491	number of C<@reason> elements (no @reason means that the port was deleted
464	"normally"). Note also that I<< the callback B<must> never die >>, so use	492	"normally"). Note also that I<< the callback B<must> never die >>, so use
465	C<eval> if unsure.	493	C<eval> if unsure.
466		494
467	In the second form (another port given), the other port (C<$rcvport>)	495	In the second form (another port given), the other port (C<$rcvport>)
468	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on	496	will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
469	"normal" kils nothing happens, while under all other conditions, the other	497	"normal" kils nothing happens, while under all other conditions, the other
470	port is killed with the same reason.	498	port is killed with the same reason.
471		499
472	The third form (kill self) is the same as the second form, except that	500	The third form (kill self) is the same as the second form, except that
473	C<$rvport> defaults to C<$SELF>.	501	C<$rvport> defaults to C<$SELF>.
…		…
476	C<snd>.	504	C<snd>.
477		505
478	As a rule of thumb, monitoring requests should always monitor a port from	506	As a rule of thumb, monitoring requests should always monitor a port from
479	a local port (or callback). The reason is that kill messages might get	507	a local port (or callback). The reason is that kill messages might get
480	lost, just like any other message. Another less obvious reason is that	508	lost, just like any other message. Another less obvious reason is that
481	even monitoring requests can get lost (for exmaple, when the connection	509	even monitoring requests can get lost (for example, when the connection
482	to the other node goes down permanently). When monitoring a port locally	510	to the other node goes down permanently). When monitoring a port locally
483	these problems do not exist.	511	these problems do not exist.
484		512
485	Example: call a given callback when C<$port> is killed.	513	Example: call a given callback when C<$port> is killed.
486		514
…		…
495	mon $port, $self => "restart";	523	mon $port, $self => "restart";
496		524
497	=cut	525	=cut
498		526
499	sub mon {	527	sub mon {
500	my ($noderef, $port) = split /#/, shift, 2;	528	my ($nodeid, $port) = split /#/, shift, 2;
501		529
502	my $node = $NODE{$noderef} \|\| add_node $noderef;	530	my $node = $NODE{$nodeid} \|\| add_node $nodeid;
503		531
504	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';	532	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
505		533
506	unless (ref $cb) {	534	unless (ref $cb) {
507	if (@_) {	535	if (@_) {
…		…
621	};	649	};
622	_self_die if $@;	650	_self_die if $@;
623	}	651	}
624		652
625	sub spawn(@) {	653	sub spawn(@) {
626	my ($noderef, undef) = split /#/, shift, 2;	654	my ($nodeid, undef) = split /#/, shift, 2;
627		655
628	my $id = "$RUNIQ." . $ID++;	656	my $id = "$RUNIQ." . $ID++;
629		657
630	$_[0] =~ /::/	658	$_[0] =~ /::/
631	or Carp::croak "spawn init function must be a fully-qualified name, caught";	659	or Carp::croak "spawn init function must be a fully-qualified name, caught";
632		660
633	snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;	661	snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
634		662
635	"$noderef#$id"	663	"$nodeid#$id"
636	}	664	}
637		665
638	=item after $timeout, @msg	666	=item after $timeout, @msg
639		667
640	=item after $timeout, $callback	668	=item after $timeout, $callback
…		…
679		707
680	=item * Node IDs are arbitrary strings in AEMP.	708	=item * Node IDs are arbitrary strings in AEMP.
681		709
682	Erlang relies on special naming and DNS to work everywhere in the same	710	Erlang relies on special naming and DNS to work everywhere in the same
683	way. AEMP relies on each node somehow knowing its own address(es) (e.g. by	711	way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
684	configuraiton or DNS), but will otherwise discover other odes itself.	712	configuration or DNS), but will otherwise discover other odes itself.
685		713
686	=item * Erlang has a "remote ports are like local ports" philosophy, AEMP	714	=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
687	uses "local ports are like remote ports".	715	uses "local ports are like remote ports".
688		716
689	The failure modes for local ports are quite different (runtime errors	717	The failure modes for local ports are quite different (runtime errors
…		…
702		730
703	Erlang uses processes that selectively receive messages, and therefore	731	Erlang uses processes that selectively receive messages, and therefore
704	needs a queue. AEMP is event based, queuing messages would serve no	732	needs a queue. AEMP is event based, queuing messages would serve no
705	useful purpose. For the same reason the pattern-matching abilities of	733	useful purpose. For the same reason the pattern-matching abilities of
706	AnyEvent::MP are more limited, as there is little need to be able to	734	AnyEvent::MP are more limited, as there is little need to be able to
707	filter messages without dequeing them.	735	filter messages without dequeuing them.
708		736
709	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).	737	(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
710		738
711	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	739	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
712		740

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.68 by root, Fri Aug 28 23:06:33 2009 UTC vs. Revision 1.78 by root, Thu Sep 3 20:16:36 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.68 by root, Fri Aug 28 23:06:33 2009 UTC vs.
Revision 1.78 by root, Thu Sep 3 20:16:36 2009 UTC