/ 
threads-lite-0.025
River stage zero No dependents
/ threads::lite

NAME

threads::lite - Yet another threads library

VERSION

Version 0.025

SYNOPSIS

 use Modern::Perl;
 use threads::lite qw/spawn self receive receive_table/;

 sub child {
     my $other = threads::lite::receive;
     while (<>) {
         chomp;
         $other->send(line => $_);
     }
 }

 my $child = spawn({ monitor => 1 } , \&child);
 $child->send(self);

 my $continue = 1;
 while ($continue) {
	 receive_table(
		 [ 'line' ] => sub {
			 my (undef, $line) = @_;
			 say "received line: $line";
		 },
		 [ 'exit', qr//, $child->id ] => sub {
			 say "received end of file";
			 $continue = 0;
		 },
		 [] => sub {
			 die sprintf "Got unknown message: (%s)", join ", ", @_;
		 },
	 );
 };

DESCRIPTION

This module implements threads for perl. One crucial difference with normal threads is that the threads are disconnected, except by message queues (channel). It thus facilitates a message passing style of multi-threading.

FUNCTIONS

All these functions are exported optionally.

Utility functions

spawn($options, $sub)

Spawn new threads. It will run $sub and send all monitoring processes it's return value. $options is a hashref that can contain the following elements.

  • modules => [...]

    Load the specified modules before running any code.

  • pool_size => int

    Create pool_size identical clones. The threads are cloned right after module load time, but before any code is run.

  • monitor => 0/1

    If this is true, the calling process will monitor the newly spawned threads. Defaults to false.

  • stack_size => int

    The stack size for the newly created threads. It defaults to 64 kiB.

$sub can be a function name or a subref. If it is a name, you must make sure the module it is in is loaded in the new thread. If it is a reference it will be serialized and sent to the new thread. This means that any enclosed variables will probability not work as expected.

self

Retreive the tid corresponding with the current thread.

Receiving functions

threads::lite defines four functions for receiving messages from the thread's mailbox. Each of them accepts matching patterns used to select those messages. Pattern matching works like this:

  • If the pattern contains more elements than the message, the match fails.

  • If the pattern contains more elements than the message, the superfluous elements are ignored for the match.

  • Each of the elements in the message is smartmatched against the corresponding element in the pattern. Smartmatching semantics are defined in perlsyn. If an element fails, the whole match fails.

  • When a match fails, the next message on the queue is tried.

receive(@pattern)

Return the first message matching pattern @pattern. If there is no such message in the queue, it blocks until a suitable message is received.

receive_nb(@pattern)

Return the first message matching pattern @pattern. If there is no such message in the queue, it returns an empty list (undef in scalar context).

receive_table( [@pattern] => action...)

This goes through each of the patterns until it can find one that matches a message on the queue, and call its action if it is defined. If none of the patterns match any of the messages in the queue, it blocks until a suitable message is received.

receive_table_nb( [@pattern] => action...)

This goes through each of the patterns until it can find one that matches a message on the queue, and call its action if it is defined. If none of the patterns match any of the messages in the queue, it blocks until a suitable message is received. If none of the patterns match any of the messages in the queue, it return an empty list.

AUTHOR

Leon Timmermans, <leont at cpan.org>

BUGS

This is an early development release, and is expected to be buggy and incomplete.

Please report any bugs or feature requests to bug-threads-lite at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=threads-lite. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc threads::lite

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 Leon Timmermans, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.