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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC vs.
Revision 1.45 by root, Thu Aug 13 01:16:24 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	# ports are message endpoints
		16
		17	# sending messages
13	snd $port, type => data...;	18	snd $port, type => data...;
		19	snd $port, @msg;
		20	snd @msg_with_first_element_being_a_port;
14		21
15	$SELF # receiving/own port id in rcv callbacks	22	# miniports
		23	my $miniport = port { my @msg = @_; 0 };
16		24
		25	# full ports
		26	my $port = port;
17	rcv $port, smartmatch => $cb->($port, @msg);	27	rcv $port, smartmatch => $cb->(@msg);
18
19	# examples:
20	rcv $port2, ping => sub { snd $_[0], "pong"; 0 };	28	rcv $port, ping => sub { snd $_[0], "pong"; 0 };
21	rcv $port1, pong => sub { warn "pong received\n" };	29	rcv $port, pong => sub { warn "pong received\n"; 0 };
22	snd $port2, ping => $port1;	30
		31	# remote ports
		32	my $port = spawn $node, $initfunc, @initdata;
23		33
24	# more, smarter, matches (_any_ is exported by this module)	34	# more, smarter, matches (_any_ is exported by this module)
25	rcv $port, [child_died => $pid] => sub { ...	35	rcv $port, [child_died => $pid] => sub { ...
26	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3	36	rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
27		37
28	# monitoring	38	# monitoring
29	mon $port, $cb->(@msg) # callback is invoked on death	39	mon $port, $cb->(@msg) # callback is invoked on death
30	mon $port, $otherport # kill otherport on abnormal death	40	mon $port, $otherport # kill otherport on abnormal death
31	mon $port, $otherport, @msg # send message on death	41	mon $port, $otherport, @msg # send message on death
32		42
		43	=head1 CURRENT STATUS
		44
		45	AnyEvent::MP - stable API, should work
		46	AnyEvent::MP::Intro - outdated
		47	AnyEvent::MP::Kernel - WIP
		48	AnyEvent::MP::Transport - mostly stable
		49
		50	stay tuned.
		51
33	=head1 DESCRIPTION	52	=head1 DESCRIPTION
34		53
35	This module (-family) implements a simple message passing framework.	54	This module (-family) implements a simple message passing framework.
36		55
37	Despite its simplicity, you can securely message other processes running	56	Despite its simplicity, you can securely message other processes running
…		…
40	For an introduction to this module family, see the L<AnyEvent::MP::Intro>	59	For an introduction to this module family, see the L<AnyEvent::MP::Intro>
41	manual page.	60	manual page.
42		61
43	At the moment, this module family is severly broken and underdocumented,	62	At the moment, this module family is severly broken and underdocumented,
44	so do not use. This was uploaded mainly to reserve the CPAN namespace -	63	so do not use. This was uploaded mainly to reserve the CPAN namespace -
45	stay tuned! The basic API should be finished, however.	64	stay tuned!
46		65
47	=head1 CONCEPTS	66	=head1 CONCEPTS
48		67
49	=over 4	68	=over 4
50		69
…		…
95		114
96	=cut	115	=cut
97		116
98	package AnyEvent::MP;	117	package AnyEvent::MP;
99		118
100	use AnyEvent::MP::Base;	119	use AnyEvent::MP::Kernel;
101		120
102	use common::sense;	121	use common::sense;
103		122
104	use Carp ();	123	use Carp ();
105		124
106	use AE ();	125	use AE ();
107		126
108	use base "Exporter";	127	use base "Exporter";
109		128
110	our $VERSION = '0.1';	129	our $VERSION = $AnyEvent::MP::Kernel::VERSION;
		130
111	our @EXPORT = qw(	131	our @EXPORT = qw(
112	NODE $NODE *SELF node_of _any_	132	NODE $NODE *SELF node_of _any_
113	resolve_node initialise_node	133	resolve_node initialise_node
114	snd rcv mon kil reg psub	134	snd rcv mon kil reg psub spawn
115	port	135	port
116	);	136	);
117		137
118	our $SELF;	138	our $SELF;
119		139
…		…
340	registered.	360	registered.
341		361
342	The global C<$SELF> (exported by this module) contains C<$port> while	362	The global C<$SELF> (exported by this module) contains C<$port> while
343	executing the callback.	363	executing the callback.
344		364
345	Runtime errors wdurign callback execution will result in the port being	365	Runtime errors during callback execution will result in the port being
346	C<kil>ed.	366	C<kil>ed.
347		367
348	If the match is an array reference, then it will be matched against the	368	If the match is an array reference, then it will be matched against the
349	first elements of the message, otherwise only the first element is being	369	first elements of the message, otherwise only the first element is being
350	matched.	370	matched.
…		…
491		511
492	=item $guard = mon $port	512	=item $guard = mon $port
493		513
494	=item $guard = mon $port, $rcvport, @msg	514	=item $guard = mon $port, $rcvport, @msg
495		515
496	Monitor the given port and do something when the port is killed, and	516	Monitor the given port and do something when the port is killed or
497	optionally return a guard that can be used to stop monitoring again.	517	messages to it were lost, and optionally return a guard that can be used
		518	to stop monitoring again.
		519
		520	C<mon> effectively guarantees that, in the absence of hardware failures,
		521	that after starting the monitor, either all messages sent to the port
		522	will arrive, or the monitoring action will be invoked after possible
		523	message loss has been detected. No messages will be lost "in between"
		524	(after the first lost message no further messages will be received by the
		525	port). After the monitoring action was invoked, further messages might get
		526	delivered again.
498		527
499	In the first form (callback), the callback is simply called with any	528	In the first form (callback), the callback is simply called with any
500	number of C<@reason> elements (no @reason means that the port was deleted	529	number of C<@reason> elements (no @reason means that the port was deleted
501	"normally"). Note also that I<< the callback B<must> never die >>, so use	530	"normally"). Note also that I<< the callback B<must> never die >>, so use
502	C<eval> if unsure.	531	C<eval> if unsure.
503		532
504	In the second form (another port given), the other port (C<$rcvport)	533	In the second form (another port given), the other port (C<$rcvport>)
505	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on	534	will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
506	"normal" kils nothing happens, while under all other conditions, the other	535	"normal" kils nothing happens, while under all other conditions, the other
507	port is killed with the same reason.	536	port is killed with the same reason.
508		537
509	The third form (kill self) is the same as the second form, except that	538	The third form (kill self) is the same as the second form, except that
…		…
536	sub mon {	565	sub mon {
537	my ($noderef, $port) = split /#/, shift, 2;	566	my ($noderef, $port) = split /#/, shift, 2;
538		567
539	my $node = $NODE{$noderef} \|\| add_node $noderef;	568	my $node = $NODE{$noderef} \|\| add_node $noderef;
540		569
541	my $cb = @_ ? $_[0] : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';	570	my $cb = @_ ? shift : $SELF \|\| Carp::croak 'mon: called with one argument only, but $SELF not set,';
542		571
543	unless (ref $cb) {	572	unless (ref $cb) {
544	if (@_) {	573	if (@_) {
545	# send a kill info message	574	# send a kill info message
546	my (@msg) = @_;	575	my (@msg) = ($cb, @_);
547	$cb = sub { snd @msg, @_ };	576	$cb = sub { snd @msg, @_ };
548	} else {	577	} else {
549	# simply kill other port	578	# simply kill other port
550	my $port = $cb;	579	my $port = $cb;
551	$cb = sub { kil $port, @_ if @_ };	580	$cb = sub { kil $port, @_ if @_ };
…		…
598	will be reported as reason C<< die => $@ >>.	627	will be reported as reason C<< die => $@ >>.
599		628
600	Transport/communication errors are reported as C<< transport_error =>	629	Transport/communication errors are reported as C<< transport_error =>
601	$message >>.	630	$message >>.
602		631
		632	=cut
		633
		634	=item $port = spawn $node, $initfunc[, @initdata]
		635
		636	Creates a port on the node C<$node> (which can also be a port ID, in which
		637	case it's the node where that port resides).
		638
		639	The port ID of the newly created port is return immediately, and it is
		640	permissible to immediately start sending messages or monitor the port.
		641
		642	After the port has been created, the init function is
		643	called. This function must be a fully-qualified function name
		644	(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main
		645	program, use C<::name>.
		646
		647	If the function doesn't exist, then the node tries to C<require>
		648	the package, then the package above the package and so on (e.g.
		649	C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
		650	exists or it runs out of package names.
		651
		652	The init function is then called with the newly-created port as context
		653	object (C<$SELF>) and the C<@initdata> values as arguments.
		654
		655	A common idiom is to pass your own port, monitor the spawned port, and
		656	in the init function, monitor the original port. This two-way monitoring
		657	ensures that both ports get cleaned up when there is a problem.
		658
		659	Example: spawn a chat server port on C<$othernode>.
		660
		661	# this node, executed from within a port context:
		662	my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
		663	mon $server;
		664
		665	# init function on C<$othernode>
		666	sub connect {
		667	my ($srcport) = @_;
		668
		669	mon $srcport;
		670
		671	rcv $SELF, sub {
		672	...
		673	};
		674	}
		675
		676	=cut
		677
		678	sub _spawn {
		679	my $port = shift;
		680	my $init = shift;
		681
		682	local $SELF = "$NODE#$port";
		683	eval {
		684	&{ load_func $init }
		685	};
		686	_self_die if $@;
		687	}
		688
		689	sub spawn(@) {
		690	my ($noderef, undef) = split /#/, shift, 2;
		691
		692	my $id = "$RUNIQ." . $ID++;
		693
		694	$_[0] =~ /::/
		695	or Carp::croak "spawn init function must be a fully-qualified name, caught";
		696
		697	($NODE{$noderef} \|\| add_node $noderef)
		698	->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
		699
		700	"$noderef#$id"
		701	}
		702
603	=back	703	=back
604		704
605	=head1 NODE MESSAGES	705	=head1 NODE MESSAGES
606		706
607	Nodes understand the following messages sent to them. Many of them take	707	Nodes understand the following messages sent to them. Many of them take

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC vs. Revision 1.45 by root, Thu Aug 13 01:16:24 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.37 by root, Fri Aug 7 16:47:23 2009 UTC vs.
Revision 1.45 by root, Thu Aug 13 01:16:24 2009 UTC