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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.69 by root, Sun Aug 30 18:51:49 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, key => value...	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 first 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). the profile is calculated as follows:	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.
182		183
183	First, all remaining key => value pairs will be used. Then they will be	184	The profile data is then gathered as follows:
184	overwritten by any values specified in the global default configuration	185
185	(see the F<aemp> utility), then the chain of profiles selected, if	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
186	any. That means that the values specified in the profile have highest	192	That means that the values specified in the profile have highest priority
187	priority and the values specified via C<initialise_node> have lowest	193	and the values specified directly via C<configure> have lowest priority,
188	priority.	194	and can only be used to specify defaults.
189		195
190	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
191	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
192	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
193		201
194	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
195	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
196	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
197	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
198	binds, but it can still talk to all "normal" nodes).	206	binds, but it can still talk to all "normal" nodes).
199		207
200	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
201	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
202	used as binds list.	210	local IP address it finds.
203		211
		212	=item step 3, connect to seed nodes
		213
204	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
205	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
206	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.
207		217
208	Example: become a distributed node listening on the guessed noderef, or	218	=back
209	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.
210	most common form of invocation for "daemon"-type nodes.	221	This should be the most common form of invocation for "daemon"-type nodes.
211		222
212	initialise_node;	223	configure
213		224
214	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
215	clients.	226	clients.
216		227
217	initialise_node "anon/";	228	configure nodeid => "anon/";
218		229
219	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
220	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,
221	on the resulting addresses.	232	customary for aemp).
222		233
223	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)"
224		245
225	=item $SELF	246	=item $SELF
226		247
227	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>
228	blocks.	249	blocks.
…		…
350		371
351	=cut	372	=cut
352		373
353	sub rcv($@) {	374	sub rcv($@) {
354	my $port = shift;	375	my $port = shift;
355	my ($noderef, $portid) = split /#/, $port, 2;	376	my ($nodeid, $portid) = split /#/, $port, 2;
356		377
357	$NODE{$noderef} == $NODE{""}	378	$NODE{$nodeid} == $NODE{""}
358	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";
359		380
360	while (@_) {	381	while (@_) {
361	if (ref $_[0]) {	382	if (ref $_[0]) {
362	if (my $self = $PORT_DATA{$portid}) {	383	if (my $self = $PORT_DATA{$portid}) {
…		…
470	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
471	"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
472	C<eval> if unsure.	493	C<eval> if unsure.
473		494
474	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>)
475	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
476	"normal" kils nothing happens, while under all other conditions, the other	497	"normal" kils nothing happens, while under all other conditions, the other
477	port is killed with the same reason.	498	port is killed with the same reason.
478		499
479	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
480	C<$rvport> defaults to C<$SELF>.	501	C<$rvport> defaults to C<$SELF>.
…		…
483	C<snd>.	504	C<snd>.
484		505
485	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
486	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
487	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
488	even monitoring requests can get lost (for exmaple, when the connection	509	even monitoring requests can get lost (for example, when the connection
489	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
490	these problems do not exist.	511	these problems do not exist.
491		512
492	Example: call a given callback when C<$port> is killed.	513	Example: call a given callback when C<$port> is killed.
493		514
…		…
502	mon $port, $self => "restart";	523	mon $port, $self => "restart";
503		524
504	=cut	525	=cut
505		526
506	sub mon {	527	sub mon {
507	my ($noderef, $port) = split /#/, shift, 2;	528	my ($nodeid, $port) = split /#/, shift, 2;
508		529
509	my $node = $NODE{$noderef} \|\| add_node $noderef;	530	my $node = $NODE{$nodeid} \|\| add_node $nodeid;
510		531
511	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,';
512		533
513	unless (ref $cb) {	534	unless (ref $cb) {
514	if (@_) {	535	if (@_) {
…		…
628	};	649	};
629	_self_die if $@;	650	_self_die if $@;
630	}	651	}
631		652
632	sub spawn(@) {	653	sub spawn(@) {
633	my ($noderef, undef) = split /#/, shift, 2;	654	my ($nodeid, undef) = split /#/, shift, 2;
634		655
635	my $id = "$RUNIQ." . $ID++;	656	my $id = "$RUNIQ." . $ID++;
636		657
637	$_[0] =~ /::/	658	$_[0] =~ /::/
638	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";
639		660
640	snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_;	661	snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
641		662
642	"$noderef#$id"	663	"$nodeid#$id"
643	}	664	}
644		665
645	=item after $timeout, @msg	666	=item after $timeout, @msg
646		667
647	=item after $timeout, $callback	668	=item after $timeout, $callback
…		…
686		707
687	=item * Node IDs are arbitrary strings in AEMP.	708	=item * Node IDs are arbitrary strings in AEMP.
688		709
689	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
690	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
691	configuraiton or DNS), but will otherwise discover other odes itself.	712	configuration or DNS), but will otherwise discover other odes itself.
692		713
693	=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
694	uses "local ports are like remote ports".	715	uses "local ports are like remote ports".
695		716
696	The failure modes for local ports are quite different (runtime errors	717	The failure modes for local ports are quite different (runtime errors
…		…
709		730
710	Erlang uses processes that selectively receive messages, and therefore	731	Erlang uses processes that selectively receive messages, and therefore
711	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
712	useful purpose. For the same reason the pattern-matching abilities of	733	useful purpose. For the same reason the pattern-matching abilities of
713	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
714	filter messages without dequeing them.	735	filter messages without dequeuing them.
715		736
716	(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).
717		738
718	=item * Erlang sends are synchronous, AEMP sends are asynchronous.	739	=item * Erlang sends are synchronous, AEMP sends are asynchronous.
719		740

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.69 by root, Sun Aug 30 18:51:49 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.69 by root, Sun Aug 30 18:51:49 2009 UTC vs.
Revision 1.78 by root, Thu Sep 3 20:16:36 2009 UTC