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

NAME

threads::lite - Actor model threading for Perl

VERSION

Version 0.034

SYNOPSIS

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

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

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

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

DESCRIPTION

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

Please note that this module is a research project. In no way is API stability guaranteed. It is released for evaluation purposes only, not for production usage.

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.

  • 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 to a function it will be serialized before being sent to the new thread. This means that any enclosed variables will probability not work as expected. Any locally imported functions will not be defined in the new thread, so you probably want to use fully qualified names.

self()

Retreive the thread identifier object corresponding with the current thread.

send_to($id, ...)

Send a message a thread identified by its primitive identifier

Receiving functions

All these functions will try to match messages in the local thread's mailbox to a pattern. If it can find a match, the message will be removed from the mailbox.

receive { ... }

Match each message against the code in the block until a message matches it. The block is expected to contain when and default blocks, but may contain other code too. If no matching message is found, it will block until a suitable message is received.

receive_nb { ... }

Match in exactly the same way receive does, but do not block if no suitable message can be found. Instead it will return an empty list.

receiveq(@pattern)

Return the first message that smart-matches @pattern. If there is no such message in the queue, it blocks until a suitable message is received. An empty pattern results in the first message

receiveq_nb(@pattern)

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

AUTHOR

Leon Timmermans, <leont at cpan.org>

BUGS

This is an early development release, and is expected to be buggy and incomplete. In particular, memory management is known to be buggy.

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, 2010, 2011 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.