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

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.31 by root, Wed Aug 5 19:55:58 2009 UTC vs.
Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC

…		…
123	The C<NODE> function returns, and the C<$NODE> variable contains	123	The C<NODE> function returns, and the C<$NODE> variable contains
124	the noderef of the local node. The value is initialised by a call	124	the noderef of the local node. The value is initialised by a call
125	to C<become_public> or C<become_slave>, after which all local port	125	to C<become_public> or C<become_slave>, after which all local port
126	identifiers become invalid.	126	identifiers become invalid.
127		127
128	=item $noderef = node_of $portid	128	=item $noderef = node_of $port
129		129
130	Extracts and returns the noderef from a portid or a noderef.	130	Extracts and returns the noderef from a portid or a noderef.
131		131
132	=item $cv = resolve_node $noderef	132	=item $cv = resolve_node $noderef
133		133
…		…
167		167
168	Due to some quirks in how perl exports variables, it is impossible to	168	Due to some quirks in how perl exports variables, it is impossible to
169	just export C<$SELF>, all the symbols called C<SELF> are exported by this	169	just export C<$SELF>, all the symbols called C<SELF> are exported by this
170	module, but only C<$SELF> is currently used.	170	module, but only C<$SELF> is currently used.
171		171
172	=item snd $portid, type => @data	172	=item snd $port, type => @data
173		173
174	=item snd $portid, @msg	174	=item snd $port, @msg
175		175
176	Send the given message to the given port ID, which can identify either	176	Send the given message to the given port ID, which can identify either
177	a local or a remote port, and can be either a string or soemthignt hat	177	a local or a remote port, and can be either a string or soemthignt hat
178	stringifies a sa port ID (such as a port object :).	178	stringifies a sa port ID (such as a port object :).
179		179
…		…
189	JSON is used, then only strings, numbers and arrays and hashes consisting	189	JSON is used, then only strings, numbers and arrays and hashes consisting
190	of those are allowed (no objects). When Storable is used, then anything	190	of those are allowed (no objects). When Storable is used, then anything
191	that Storable can serialise and deserialise is allowed, and for the local	191	that Storable can serialise and deserialise is allowed, and for the local
192	node, anything can be passed.	192	node, anything can be passed.
193		193
194	=item kil $portid[, @reason]	194	=item $local_port = port
195		195
196	Kill the specified port with the given C<@reason>.	196	Create a new local port object that can be used either as a pattern
		197	matching port ("full port") or a single-callback port ("miniport"),
		198	depending on how C<rcv> callbacks are bound to the object.
197		199
198	If no C<@reason> is specified, then the port is killed "normally" (linked	200	=item $port = port { my @msg = @_; $finished }
199	ports will not be kileld, or even notified).
200		201
201	Otherwise, linked ports get killed with the same reason (second form of	202	Creates a "miniport", that is, a very lightweight port without any pattern
202	C<mon>, see below).	203	matching behind it, and returns its ID. Semantically the same as creating
		204	a port and calling C<rcv $port, $callback> on it.
203		205
204	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks	206	The block will be called for every message received on the port. When the
205	will be reported as reason C<< die => $@ >>.	207	callback returns a true value its job is considered "done" and the port
		208	will be destroyed. Otherwise it will stay alive.
206		209
207	Transport/communication errors are reported as C<< transport_error =>	210	The message will be passed as-is, no extra argument (i.e. no port id) will
208	$message >>.	211	be passed to the callback.
209		212
		213	If you need the local port id in the callback, this works nicely:
		214
		215	my $port; $port = port {
		216	snd $otherport, reply => $port;
		217	};
		218
		219	=cut
		220
		221	sub rcv($@);
		222
		223	sub port(;&) {
		224	my $id = "$UNIQ." . $ID++;
		225	my $port = "$NODE#$id";
		226
		227	if (@_) {
		228	rcv $port, shift;
		229	} else {
		230	$PORT{$id} = sub { }; # nop
		231	}
		232
		233	$port
		234	}
		235
		236	=item reg $port, $name
		237
		238	Registers the given port under the name C<$name>. If the name already
		239	exists it is replaced.
		240
		241	A port can only be registered under one well known name.
		242
		243	A port automatically becomes unregistered when it is killed.
		244
		245	=cut
		246
		247	sub reg(@) {
		248	my ($port, $name) = @_;
		249
		250	$REG{$name} = $port;
		251	}
		252
		253	=item rcv $port, $callback->(@msg)
		254
		255	Replaces the callback on the specified miniport (after converting it to
		256	one if required).
		257
		258	=item rcv $port, tagstring => $callback->(@msg), ...
		259
		260	=item rcv $port, $smartmatch => $callback->(@msg), ...
		261
		262	=item rcv $port, [$smartmatch...] => $callback->(@msg), ...
		263
		264	Register callbacks to be called on matching messages on the given full
		265	port (after converting it to one if required).
		266
		267	The callback has to return a true value when its work is done, after
		268	which is will be removed, or a false value in which case it will stay
		269	registered.
		270
		271	The global C<$SELF> (exported by this module) contains C<$port> while
		272	executing the callback.
		273
		274	Runtime errors wdurign callback execution will result in the port being
		275	C<kil>ed.
		276
		277	If the match is an array reference, then it will be matched against the
		278	first elements of the message, otherwise only the first element is being
		279	matched.
		280
		281	Any element in the match that is specified as C<_any_> (a function
		282	exported by this module) matches any single element of the message.
		283
		284	While not required, it is highly recommended that the first matching
		285	element is a string identifying the message. The one-string-only match is
		286	also the most efficient match (by far).
		287
		288	=cut
		289
		290	sub rcv($@) {
		291	my $port = shift;
		292	my ($noderef, $portid) = split /#/, $port, 2;
		293
		294	($NODE{$noderef} \|\| add_node $noderef) == $NODE{""}
		295	or Carp::croak "$port: rcv can only be called on local ports, caught";
		296
		297	if (@_ == 1) {
		298	my $cb = shift;
		299	delete $PORT_DATA{$portid};
		300	$PORT{$portid} = sub {
		301	local $SELF = $port;
		302	eval {
		303	&$cb
		304	and kil $port;
		305	};
		306	_self_die if $@;
		307	};
		308	} else {
		309	my $self = $PORT_DATA{$portid} \|\|= do {
		310	my $self = bless {
		311	id => $port,
		312	}, "AnyEvent::MP::Port";
		313
		314	$PORT{$portid} = sub {
		315	local $SELF = $port;
		316
		317	eval {
		318	for (@{ $self->{rc0}{$_[0]} }) {
		319	$_ && &{$_->[0]}
		320	&& undef $_;
		321	}
		322
		323	for (@{ $self->{rcv}{$_[0]} }) {
		324	$_ && [@_[1 .. @{$_->[1]}]] ~~ $_->[1]
		325	&& &{$_->[0]}
		326	&& undef $_;
		327	}
		328
		329	for (@{ $self->{any} }) {
		330	$_ && [@_[0 .. $#{$_->[1]}]] ~~ $_->[1]
		331	&& &{$_->[0]}
		332	&& undef $_;
		333	}
		334	};
		335	_self_die if $@;
		336	};
		337
		338	$self
		339	};
		340
		341	"AnyEvent::MP::Port" eq ref $self
		342	or Carp::croak "$port: rcv can only be called on message matching ports, caught";
		343
		344	while (@_) {
		345	my ($match, $cb) = splice @_, 0, 2;
		346
		347	if (!ref $match) {
		348	push @{ $self->{rc0}{$match} }, [$cb];
		349	} elsif (("ARRAY" eq ref $match && !ref $match->[0])) {
		350	my ($type, @match) = @$match;
		351	@match
		352	? push @{ $self->{rcv}{$match->[0]} }, [$cb, \@match]
		353	: push @{ $self->{rc0}{$match->[0]} }, [$cb];
		354	} else {
		355	push @{ $self->{any} }, [$cb, $match];
		356	}
		357	}
		358	}
		359
		360	$port
		361	}
		362
		363	=item $closure = psub { BLOCK }
		364
		365	Remembers C<$SELF> and creates a closure out of the BLOCK. When the
		366	closure is executed, sets up the environment in the same way as in C<rcv>
		367	callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
		368
		369	This is useful when you register callbacks from C<rcv> callbacks:
		370
		371	rcv delayed_reply => sub {
		372	my ($delay, @reply) = @_;
		373	my $timer = AE::timer $delay, 0, psub {
		374	snd @reply, $SELF;
		375	};
		376	};
		377
		378	=cut
		379
		380	sub psub(&) {
		381	my $cb = shift;
		382
		383	my $port = $SELF
		384	or Carp::croak "psub can only be called from within rcv or psub callbacks, not";
		385
		386	sub {
		387	local $SELF = $port;
		388
		389	if (wantarray) {
		390	my @res = eval { &$cb };
		391	_self_die if $@;
		392	@res
		393	} else {
		394	my $res = eval { &$cb };
		395	_self_die if $@;
		396	$res
		397	}
		398	}
		399	}
		400
210	=item $guard = mon $portid, $cb->(@reason)	401	=item $guard = mon $port, $cb->(@reason)
211		402
212	=item $guard = mon $portid, $otherport	403	=item $guard = mon $port, $otherport
213		404
214	=item $guard = mon $portid, $otherport, @msg	405	=item $guard = mon $port, $otherport, @msg
215		406
216	Monitor the given port and do something when the port is killed.	407	Monitor the given port and do something when the port is killed.
217		408
218	In the first form, the callback is simply called with any number	409	In the first form, the callback is simply called with any number
219	of C<@reason> elements (no @reason means that the port was deleted	410	of C<@reason> elements (no @reason means that the port was deleted
…		…
297	mon $port2, $port1;	488	mon $port2, $port1;
298		489
299	It means that if either one is killed abnormally, the other one gets	490	It means that if either one is killed abnormally, the other one gets
300	killed as well.	491	killed as well.
301		492
302	=item $local_port = port	493	=item kil $port[, @reason]
303		494
304	Create a new local port object that can be used either as a pattern	495	Kill the specified port with the given C<@reason>.
305	matching port ("full port") or a single-callback port ("miniport"),
306	depending on how C<rcv> callbacks are bound to the object.
307		496
308	=item $portid = port { my @msg = @_; $finished }	497	If no C<@reason> is specified, then the port is killed "normally" (linked
		498	ports will not be kileld, or even notified).
309		499
310	Creates a "mini port", that is, a very lightweight port without any	500	Otherwise, linked ports get killed with the same reason (second form of
311	pattern matching behind it, and returns its ID.	501	C<mon>, see below).
312		502
313	The block will be called for every message received on the port. When the	503	Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
314	callback returns a true value its job is considered "done" and the port	504	will be reported as reason C<< die => $@ >>.
315	will be destroyed. Otherwise it will stay alive.
316		505
317	The message will be passed as-is, no extra argument (i.e. no port id) will	506	Transport/communication errors are reported as C<< transport_error =>
318	be passed to the callback.	507	$message >>.
319
320	If you need the local port id in the callback, this works nicely:
321
322	my $port; $port = port {
323	snd $otherport, reply => $port;
324	};
325
326	=cut
327
328	sub port(;&) {
329	my $id = "$UNIQ." . $ID++;
330	my $port = "$NODE#$id";
331
332	if (@_) {
333	my $cb = shift;
334	$PORT{$id} = sub {
335	local $SELF = $port;
336	eval {
337	&$cb
338	and kil $id;
339	};
340	_self_die if $@;
341	};
342	} else {
343	my $self = bless {
344	id => "$NODE#$id",
345	}, "AnyEvent::MP::Port";
346
347	$PORT_DATA{$id} = $self;
348	$PORT{$id} = sub {
349	local $SELF = $port;
350
351	eval {
352	for (@{ $self->{rc0}{$_[0]} }) {
353	$_ && &{$_->[0]}
354	&& undef $_;
355	}
356
357	for (@{ $self->{rcv}{$_[0]} }) {
358	$_ && [@_[1 .. @{$_->[1]}]] ~~ $_->[1]
359	&& &{$_->[0]}
360	&& undef $_;
361	}
362
363	for (@{ $self->{any} }) {
364	$_ && [@_[0 .. $#{$_->[1]}]] ~~ $_->[1]
365	&& &{$_->[0]}
366	&& undef $_;
367	}
368	};
369	_self_die if $@;
370	};
371	}
372
373	$port
374	}
375
376	=item reg $portid, $name
377
378	Registers the given port under the name C<$name>. If the name already
379	exists it is replaced.
380
381	A port can only be registered under one well known name.
382
383	A port automatically becomes unregistered when it is killed.
384
385	=cut
386
387	sub reg(@) {
388	my ($portid, $name) = @_;
389
390	$REG{$name} = $portid;
391	}
392
393	=item rcv $portid, $callback->(@msg)
394
395	Replaces the callback on the specified miniport (or newly created port
396	object, see C<port>). Full ports are configured with the following calls:
397
398	=item rcv $portid, tagstring => $callback->(@msg), ...
399
400	=item rcv $portid, $smartmatch => $callback->(@msg), ...
401
402	=item rcv $portid, [$smartmatch...] => $callback->(@msg), ...
403
404	Register callbacks to be called on matching messages on the given port.
405
406	The callback has to return a true value when its work is done, after
407	which is will be removed, or a false value in which case it will stay
408	registered.
409
410	The global C<$SELF> (exported by this module) contains C<$portid> while
411	executing the callback.
412
413	Runtime errors wdurign callback execution will result in the port being
414	C<kil>ed.
415
416	If the match is an array reference, then it will be matched against the
417	first elements of the message, otherwise only the first element is being
418	matched.
419
420	Any element in the match that is specified as C<_any_> (a function
421	exported by this module) matches any single element of the message.
422
423	While not required, it is highly recommended that the first matching
424	element is a string identifying the message. The one-string-only match is
425	also the most efficient match (by far).
426
427	=cut
428
429	sub rcv($@) {
430	my $portid = shift;
431	my ($noderef, $port) = split /#/, $port, 2;
432
433	($NODE{$noderef} \|\| add_node $noderef) == $NODE{""}
434	or Carp::croak "$noderef#$port: rcv can only be called on local ports, caught";
435
436	my $self = $PORT_DATA{$port}
437	or Carp::croak "$noderef#$port: rcv can only be called on message matching ports, caught";
438
439	"AnyEvent::MP::Port" eq ref $self
440	or Carp::croak "$noderef#$port: rcv can only be called on message matching ports, caught";
441
442	while (@_) {
443	my ($match, $cb) = splice @_, 0, 2;
444
445	if (!ref $match) {
446	push @{ $self->{rc0}{$match} }, [$cb];
447	} elsif (("ARRAY" eq ref $match && !ref $match->[0])) {
448	my ($type, @match) = @$match;
449	@match
450	? push @{ $self->{rcv}{$match->[0]} }, [$cb, \@match]
451	: push @{ $self->{rc0}{$match->[0]} }, [$cb];
452	} else {
453	push @{ $self->{any} }, [$cb, $match];
454	}
455	}
456
457	$portid
458	}
459
460	=item $closure = psub { BLOCK }
461
462	Remembers C<$SELF> and creates a closure out of the BLOCK. When the
463	closure is executed, sets up the environment in the same way as in C<rcv>
464	callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
465
466	This is useful when you register callbacks from C<rcv> callbacks:
467
468	rcv delayed_reply => sub {
469	my ($delay, @reply) = @_;
470	my $timer = AE::timer $delay, 0, psub {
471	snd @reply, $SELF;
472	};
473	};
474
475	=cut
476
477	sub psub(&) {
478	my $cb = shift;
479
480	my $port = $SELF
481	or Carp::croak "psub can only be called from within rcv or psub callbacks, not";
482
483	sub {
484	local $SELF = $port;
485
486	if (wantarray) {
487	my @res = eval { &$cb };
488	_self_die if $@;
489	@res
490	} else {
491	my $res = eval { &$cb };
492	_self_die if $@;
493	$res
494	}
495	}
496	}
497		508
498	=back	509	=back
499		510
500	=head1 FUNCTIONS FOR NODES	511	=head1 FUNCTIONS FOR NODES
501		512
502	=over 4	513	=over 4
503		514
504	=item become_public $noderef	515	=item initialise_node $noderef, $seednode, $seednode...
505		516
506	Tells the node to become a public node, i.e. reachable from other nodes.	517	=item initialise_node "slave/", $master, $master...
507		518
508	The first argument is the (unresolved) node reference of the local node	519	Initialises a node - must be called exactly once before calling other
509	(if missing then the empty string is used).	520	AnyEvent::MP functions when talking to other nodes is required.
510		521
511	It is quite common to not specify anything, in which case the local node	522	All arguments are noderefs, which can be either resolved or unresolved.
512	tries to listen on the default port, or to only specify a port number, in	523
513	which case AnyEvent::MP tries to guess the local addresses.	524	There are two types of networked nodes, public nodes and slave nodes:
		525
		526	=over 4
		527
		528	=item public nodes
		529
		530	For public nodes, C<$noderef> must either be a (possibly unresolved)
		531	noderef, in which case it will be resolved, or C<undef> (or missing), in
		532	which case the noderef will be guessed.
		533
		534	Afterwards, the node will bind itself on all endpoints and try to connect
		535	to all additional C<$seednodes> that are specified. Seednodes are optional
		536	and can be used to quickly bootstrap the node into an existing network.
		537
		538	=item slave nodes
		539
		540	When the C<$noderef> is the special string C<slave/>, then the node will
		541	become a slave node. Slave nodes cannot be contacted from outside and will
		542	route most of their traffic to the master node that they attach to.
		543
		544	At least one additional noderef is required: The node will try to connect
		545	to all of them and will become a slave attached to the first node it can
		546	successfully connect to.
		547
		548	=back
		549
		550	This function will block until all nodes have been resolved and, for slave
		551	nodes, until it has successfully established a connection to a master
		552	server.
		553
		554	Example: become a public node listening on the default node.
		555
		556	initialise_node;
		557
		558	Example: become a public node, and try to contact some well-known master
		559	servers to become part of the network.
		560
		561	initialise_node undef, "master1", "master2";
		562
		563	Example: become a public node listening on port C<4041>.
		564
		565	initialise_node 4041;
		566
		567	Example: become a public node, only visible on localhost port 4044.
		568
		569	initialise_node "locahost:4044";
		570
		571	Example: become a slave node to any of the specified master servers.
		572
		573	initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
514		574
515	=cut	575	=cut
516		576
517	=back	577	=back
518		578

Diff Legend

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

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.31 by root, Wed Aug 5 19:55:58 2009 UTC vs. Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.31 by root, Wed Aug 5 19:55:58 2009 UTC vs.
Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC