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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.35 by root, Thu Aug 6 10:21:48 2009 UTC vs.
Revision 1.48 by root, Thu Aug 13 02:59:42 2009 UTC

…		…
8		8
9	$NODE # contains this node's noderef	9	$NODE # contains this node's noderef
10	NODE # returns this node's noderef	10	NODE # returns this node's noderef
11	NODE $port # returns the noderef of the port	11	NODE $port # returns the noderef of the port
12		12
		13	$SELF # receiving/own port id in rcv callbacks
		14
		15	# initialise the node so it can send/receive messages
		16	initialise_node; # -OR-
		17	initialise_node "localhost:4040"; # -OR-
		18	initialise_node "slave/", "localhost:4040"
		19
		20	# ports are message endpoints
		21
		22	# sending messages
13	snd $port, type => data...;	23	snd $port, type => data...;
		24	snd $port, @msg;
		25	snd @msg_with_first_element_being_a_port;
14		26
15	$SELF # receiving/own port id in rcv callbacks	27	# creating/using miniports
		28	my $miniport = port { my @msg = @_; 0 };
16		29
		30	# creating/using full ports
		31	my $port = port;
17	rcv $port, smartmatch => $cb->($port, @msg);	32	rcv $port, smartmatch => $cb->(@msg);
18
19	# examples:
20	rcv $port2, ping => sub { snd $_[0], "pong"; 0 };	33	rcv $port, ping => sub { snd $_[0], "pong"; 0 };
21	rcv $port1, pong => sub { warn "pong received\n" };	34	rcv $port, pong => sub { warn "pong received\n"; 0 };
22	snd $port2, ping => $port1;
23		35
24	# more, smarter, matches (_any_ is exported by this module)	36	# more, smarter, matches (_any_ is exported by this module)
25	rcv $port, [child_died => $pid] => sub { ...	37	rcv $port, [child_died => $pid] => sub { ...
26	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3	38	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
27		39
28	# linking two ports, so they both crash together	40	# create a port on another node
29	lnk $port1, $port2;	41	my $port = spawn $node, $initfunc, @initdata;
30		42
31	# monitoring	43	# monitoring
32	mon $port, $cb->(@msg) # callback is invoked on death	44	mon $port, $cb->(@msg) # callback is invoked on death
33	mon $port, $otherport # kill otherport on abnormal death	45	mon $port, $otherport # kill otherport on abnormal death
34	mon $port, $otherport, @msg # send message on death	46	mon $port, $otherport, @msg # send message on death
35		47
		48	=head1 CURRENT STATUS
		49
		50	AnyEvent::MP - stable API, should work
		51	AnyEvent::MP::Intro - outdated
		52	AnyEvent::MP::Kernel - WIP
		53	AnyEvent::MP::Transport - mostly stable
		54
		55	stay tuned.
		56
36	=head1 DESCRIPTION	57	=head1 DESCRIPTION
37		58
38	This module (-family) implements a simple message passing framework.	59	This module (-family) implements a simple message passing framework.
39		60
40	Despite its simplicity, you can securely message other processes running	61	Despite its simplicity, you can securely message other processes running
…		…
43	For an introduction to this module family, see the L<AnyEvent::MP::Intro>	64	For an introduction to this module family, see the L<AnyEvent::MP::Intro>
44	manual page.	65	manual page.
45		66
46	At the moment, this module family is severly broken and underdocumented,	67	At the moment, this module family is severly broken and underdocumented,
47	so do not use. This was uploaded mainly to reserve the CPAN namespace -	68	so do not use. This was uploaded mainly to reserve the CPAN namespace -
48	stay tuned! The basic API should be finished, however.	69	stay tuned!
49		70
50	=head1 CONCEPTS	71	=head1 CONCEPTS
51		72
52	=over 4	73	=over 4
53		74
…		…
98		119
99	=cut	120	=cut
100		121
101	package AnyEvent::MP;	122	package AnyEvent::MP;
102		123
103	use AnyEvent::MP::Base;	124	use AnyEvent::MP::Kernel;
104		125
105	use common::sense;	126	use common::sense;
106		127
107	use Carp ();	128	use Carp ();
108		129
109	use AE ();	130	use AE ();
110		131
111	use base "Exporter";	132	use base "Exporter";
112		133
113	our $VERSION = '0.1';	134	our $VERSION = $AnyEvent::MP::Kernel::VERSION;
		135
114	our @EXPORT = qw(	136	our @EXPORT = qw(
115	NODE $NODE *SELF node_of _any_	137	NODE $NODE *SELF node_of _any_
116	resolve_node initialise_node	138	resolve_node initialise_node
117	snd rcv mon kil reg psub	139	snd rcv mon kil reg psub spawn
118	port	140	port
119	);	141	);
120		142
121	our $SELF;	143	our $SELF;
122		144
…		…
305	$port	327	$port
306	}	328	}
307		329
308	=item reg $port, $name	330	=item reg $port, $name
309		331
310	Registers the given port under the name C<$name>. If the name already	332	=item reg $name
311	exists it is replaced.	333
		334	Registers the given port (or C<$SELF><<< if missing) under the name
		335	C<$name>. If the name already exists it is replaced.
312		336
313	A port can only be registered under one well known name.	337	A port can only be registered under one well known name.
314		338
315	A port automatically becomes unregistered when it is killed.	339	A port automatically becomes unregistered when it is killed.
316		340
317	=cut	341	=cut
318		342
319	sub reg(@) {	343	sub reg(@) {
320	my ($port, $name) = @_;	344	my $port = @_ > 1 ? shift : $SELF \|\| Carp::croak 'reg: called with one argument only, but $SELF not set,';
321		345
322	$REG{$name} = $port;	346	$REG{$_[0]} = $port;
323	}	347	}
324		348
325	=item rcv $port, $callback->(@msg)	349	=item rcv $port, $callback->(@msg)
326		350
327	Replaces the callback on the specified miniport (after converting it to	351	Replaces the callback on the specified miniport (after converting it to
…		…
332	=item rcv $port, $smartmatch => $callback->(@msg), ...	356	=item rcv $port, $smartmatch => $callback->(@msg), ...
333		357
334	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...	358	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...
335		359
336	Register callbacks to be called on matching messages on the given full	360	Register callbacks to be called on matching messages on the given full
337	port (after converting it to one if required).	361	port (after converting it to one if required) and return the port.
338		362
339	The callback has to return a true value when its work is done, after	363	The callback has to return a true value when its work is done, after
340	which is will be removed, or a false value in which case it will stay	364	which is will be removed, or a false value in which case it will stay
341	registered.	365	registered.
342		366
343	The global C<$SELF> (exported by this module) contains C<$port> while	367	The global C<$SELF> (exported by this module) contains C<$port> while
344	executing the callback.	368	executing the callback.
345		369
346	Runtime errors wdurign callback execution will result in the port being	370	Runtime errors during callback execution will result in the port being
347	C<kil>ed.	371	C<kil>ed.
348		372
349	If the match is an array reference, then it will be matched against the	373	If the match is an array reference, then it will be matched against the
350	first elements of the message, otherwise only the first element is being	374	first elements of the message, otherwise only the first element is being
351	matched.	375	matched.
…		…
354	exported by this module) matches any single element of the message.	378	exported by this module) matches any single element of the message.
355		379
356	While not required, it is highly recommended that the first matching	380	While not required, it is highly recommended that the first matching
357	element is a string identifying the message. The one-string-only match is	381	element is a string identifying the message. The one-string-only match is
358	also the most efficient match (by far).	382	also the most efficient match (by far).
		383
		384	Example: create a port and bind receivers on it in one go.
		385
		386	my $port = rcv port,
		387	msg1 => sub { ...; 0 },
		388	msg2 => sub { ...; 0 },
		389	;
		390
		391	Example: create a port, bind receivers and send it in a message elsewhere
		392	in one go:
		393
		394	snd $otherport, reply =>
		395	rcv port,
		396	msg1 => sub { ...; 0 },
		397	...
		398	;
359		399
360	=cut	400	=cut
361		401
362	sub rcv($@) {	402	sub rcv($@) {
363	my $port = shift;	403	my $port = shift;
…		…
470	}	510	}
471	}	511	}
472		512
473	=item $guard = mon $port, $cb->(@reason)	513	=item $guard = mon $port, $cb->(@reason)
474		514
475	=item $guard = mon $port, $otherport	515	=item $guard = mon $port, $rcvport
476		516
		517	=item $guard = mon $port
		518
477	=item $guard = mon $port, $otherport, @msg	519	=item $guard = mon $port, $rcvport, @msg
478		520
479	Monitor the given port and do something when the port is killed.	521	Monitor the given port and do something when the port is killed or
		522	messages to it were lost, and optionally return a guard that can be used
		523	to stop monitoring again.
480		524
		525	C<mon> effectively guarantees that, in the absence of hardware failures,
		526	that after starting the monitor, either all messages sent to the port
		527	will arrive, or the monitoring action will be invoked after possible
		528	message loss has been detected. No messages will be lost "in between"
		529	(after the first lost message no further messages will be received by the
		530	port). After the monitoring action was invoked, further messages might get
		531	delivered again.
		532
481	In the first form, the callback is simply called with any number	533	In the first form (callback), the callback is simply called with any
482	of C<@reason> elements (no @reason means that the port was deleted	534	number of C<@reason> elements (no @reason means that the port was deleted
483	"normally"). Note also that I<< the callback B<must> never die >>, so use	535	"normally"). Note also that I<< the callback B<must> never die >>, so use
484	C<eval> if unsure.	536	C<eval> if unsure.
485		537
486	In the second form, the other port will be C<kil>'ed with C<@reason>, iff	538	In the second form (another port given), the other port (C<$rcvport>)
487	a @reason was specified, i.e. on "normal" kils nothing happens, while	539	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
488	under all other conditions, the other port is killed with the same reason.	540	"normal" kils nothing happens, while under all other conditions, the other
		541	port is killed with the same reason.
489		542
		543	The third form (kill self) is the same as the second form, except that
		544	C<$rvport> defaults to C<$SELF>.
		545
490	In the last form, a message of the form C<@msg, @reason> will be C<snd>.	546	In the last form (message), a message of the form C<@msg, @reason> will be
		547	C<snd>.
		548
		549	As a rule of thumb, monitoring requests should always monitor a port from
		550	a local port (or callback). The reason is that kill messages might get
		551	lost, just like any other message. Another less obvious reason is that
		552	even monitoring requests can get lost (for exmaple, when the connection
		553	to the other node goes down permanently). When monitoring a port locally
		554	these problems do not exist.
491		555
492	Example: call a given callback when C<$port> is killed.	556	Example: call a given callback when C<$port> is killed.
493		557
494	mon $port, sub { warn "port died because of <@_>\n" };	558	mon $port, sub { warn "port died because of <@_>\n" };
495		559
496	Example: kill ourselves when C<$port> is killed abnormally.	560	Example: kill ourselves when C<$port> is killed abnormally.
497		561
498	mon $port, $self;	562	mon $port;
499		563
500	Example: send us a restart message another C<$port> is killed.	564	Example: send us a restart message when another C<$port> is killed.
501		565
502	mon $port, $self => "restart";	566	mon $port, $self => "restart";
503		567
504	=cut	568	=cut
505		569
506	sub mon {	570	sub mon {
507	my ($noderef, $port) = split /#/, shift, 2;	571	my ($noderef, $port) = split /#/, shift, 2;
508		572
509	my $node = $NODE{$noderef} \|\| add_node $noderef;	573	my $node = $NODE{$noderef} \|\| add_node $noderef;
510		574
511	my $cb = shift;	575	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
512		576
513	unless (ref $cb) {	577	unless (ref $cb) {
514	if (@_) {	578	if (@_) {
515	# send a kill info message	579	# send a kill info message
516	my (@msg) = ($cb, @_);	580	my (@msg) = ($cb, @_);
…		…
547	=cut	611	=cut
548		612
549	sub mon_guard {	613	sub mon_guard {
550	my ($port, @refs) = @_;	614	my ($port, @refs) = @_;
551		615
		616	#TODO: mon-less form?
		617
552	mon $port, sub { 0 && @refs }	618	mon $port, sub { 0 && @refs }
553	}	619	}
554		620
555	=item lnk $port1, $port2
556
557	Link two ports. This is simply a shorthand for:
558
559	mon $port1, $port2;
560	mon $port2, $port1;
561
562	It means that if either one is killed abnormally, the other one gets
563	killed as well.
564
565	=item kil $port[, @reason]	621	=item kil $port[, @reason]
566		622
567	Kill the specified port with the given C<@reason>.	623	Kill the specified port with the given C<@reason>.
568		624
569	If no C<@reason> is specified, then the port is killed "normally" (linked	625	If no C<@reason> is specified, then the port is killed "normally" (linked
…		…
575	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks	631	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
576	will be reported as reason C<< die => $@ >>.	632	will be reported as reason C<< die => $@ >>.
577		633
578	Transport/communication errors are reported as C<< transport_error =>	634	Transport/communication errors are reported as C<< transport_error =>
579	$message >>.	635	$message >>.
		636
		637	=cut
		638
		639	=item $port = spawn $node, $initfunc[, @initdata]
		640
		641	Creates a port on the node C<$node> (which can also be a port ID, in which
		642	case it's the node where that port resides).
		643
		644	The port ID of the newly created port is return immediately, and it is
		645	permissible to immediately start sending messages or monitor the port.
		646
		647	After the port has been created, the init function is
		648	called. This function must be a fully-qualified function name
		649	(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main
		650	program, use C<::name>.
		651
		652	If the function doesn't exist, then the node tries to C<require>
		653	the package, then the package above the package and so on (e.g.
		654	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
		655	exists or it runs out of package names.
		656
		657	The init function is then called with the newly-created port as context
		658	object (C<$SELF>) and the C<@initdata> values as arguments.
		659
		660	A common idiom is to pass your own port, monitor the spawned port, and
		661	in the init function, monitor the original port. This two-way monitoring
		662	ensures that both ports get cleaned up when there is a problem.
		663
		664	Example: spawn a chat server port on C<$othernode>.
		665
		666	# this node, executed from within a port context:
		667	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
		668	mon $server;
		669
		670	# init function on C<$othernode>
		671	sub connect {
		672	my ($srcport) = @_;
		673
		674	mon $srcport;
		675
		676	rcv $SELF, sub {
		677	...
		678	};
		679	}
		680
		681	=cut
		682
		683	sub _spawn {
		684	my $port = shift;
		685	my $init = shift;
		686
		687	local $SELF = "$NODE#$port";
		688	eval {
		689	&{ load_func $init }
		690	};
		691	_self_die if $@;
		692	}
		693
		694	sub spawn(@) {
		695	my ($noderef, undef) = split /#/, shift, 2;
		696
		697	my $id = "$RUNIQ." . $ID++;
		698
		699	$_[0] =~ /::/
		700	or Carp::croak "spawn init function must be a fully-qualified name, caught";
		701
		702	($NODE{$noderef} \|\| add_node $noderef)
		703	->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
		704
		705	"$noderef#$id"
		706	}
580		707
581	=back	708	=back
582		709
583	=head1 NODE MESSAGES	710	=head1 NODE MESSAGES
584		711
…		…
717	or I<none>, there is no in-between, so monitoring single processes is	844	or I<none>, there is no in-between, so monitoring single processes is
718	difficult to implement. Monitoring in AEMP is more flexible than in	845	difficult to implement. Monitoring in AEMP is more flexible than in
719	Erlang, as one can choose between automatic kill, exit message or callback	846	Erlang, as one can choose between automatic kill, exit message or callback
720	on a per-process basis.	847	on a per-process basis.
721		848
722	=item * Erlang has different semantics for monitoring and linking, AEMP has the same.	849	=item * Erlang tries to hide remote/local connections, AEMP does not.
723		850
724	Monitoring in Erlang is not an indicator of process death/crashes,	851	Monitoring in Erlang is not an indicator of process death/crashes,
725	as linking is (except linking is unreliable in Erlang). In AEMP, the	852	as linking is (except linking is unreliable in Erlang).
726	semantics of monitoring and linking are identical, linking is simply	853
727	two-way monitoring with automatic kill.	854	In AEMP, you don't "look up" registered port names or send to named ports
		855	that might or might not be persistent. Instead, you normally spawn a port
		856	on the remote node. The init function monitors the you, and you monitor
		857	the remote port. Since both monitors are local to the node, they are much
		858	more reliable.
		859
		860	This also saves round-trips and avoids sending messages to the wrong port
		861	(hard to do in Erlang).
		862
		863	=back
		864
		865	=head1 RATIONALE
		866
		867	=over 4
		868
		869	=item Why strings for ports and noderefs, why not objects?
		870
		871	We considered "objects", but found that the actual number of methods
		872	thatc an be called are very low. Since port IDs and noderefs travel over
		873	the network frequently, the serialising/deserialising would add lots of
		874	overhead, as well as having to keep a proxy object.
		875
		876	Strings can easily be printed, easily serialised etc. and need no special
		877	procedures to be "valid".
		878
		879	And a a miniport consists of a single closure stored in a global hash - it
		880	can't become much cheaper.
		881
		882	=item Why favour JSON, why not real serialising format such as Storable?
		883
		884	In fact, any AnyEvent::MP node will happily accept Storable as framing
		885	format, but currently there is no way to make a node use Storable by
		886	default.
		887
		888	The default framing protocol is JSON because a) JSON::XS is many times
		889	faster for small messages and b) most importantly, after years of
		890	experience we found that object serialisation is causing more problems
		891	than it gains: Just like function calls, objects simply do not travel
		892	easily over the network, mostly because they will always be a copy, so you
		893	always have to re-think your design.
		894
		895	Keeping your messages simple, concentrating on data structures rather than
		896	objects, will keep your messages clean, tidy and efficient.
728		897
729	=back	898	=back
730		899
731	=head1 SEE ALSO	900	=head1 SEE ALSO
732		901

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.35 by root, Thu Aug 6 10:21:48 2009 UTC vs. Revision 1.48 by root, Thu Aug 13 02:59:42 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.35 by root, Thu Aug 6 10:21:48 2009 UTC vs.
Revision 1.48 by root, Thu Aug 13 02:59:42 2009 UTC