Thread-Queue-Any-1.17/0000755000175000017500000000000015000433645013520 5ustar rockyrockyThread-Queue-Any-1.17/MANIFEST0000644000175000017500000000075512313563212014656 0ustar rockyrockyMANIFEST MANIFEST_maint CHANGELOG README TODO Makefile.PL lib_maint/Thread/Queue/Any.pm_maint lib/Thread/Queue/Any.pm t/001basic.t t/010serializer.t t_maint/Queue-Any.t_maint META.yml Module meta-data (added by MakeMaker) threadsforks threads/forks test (added by Devel::ThreadsForks) maintblead maint/blead test (added by Devel::MaintBlead) META.json Module JSON meta-data (added by MakeMaker) Thread-Queue-Any-1.17/t/0000755000175000017500000000000015000433645013763 5ustar rockyrockyThread-Queue-Any-1.17/t/001basic.t0000644000175000017500000000475112313562344015464 0ustar rockyrockyBEGIN { # Magic Perl CORE pragma if ($ENV{PERL_CORE}) { chdir 't' if -d 't'; @INC = '../lib'; } } use strict; use warnings; my %Loaded; BEGIN { $Loaded{threads}= eval "use threads; 1"; $Loaded{forks}= eval "use forks; 1" if !$Loaded{threads}; } use Thread::Queue::Any; use Test::More; diag "threads loaded" if $Loaded{threads}; diag "forks loaded" if $Loaded{forks}; ok( $Loaded{threads} || $Loaded{forks}, "thread-like module loaded" ); my $class= 'Thread::Queue::Any'; my $q= $class->new; isa_ok( $q, $class, 'check object type' ); can_ok( $q, qw( dequeue dequeue_dontwait dequeue_keep dequeue_nb enqueue new pending THAW ) ); # enqueing $q->enqueue( qw( a b c ) ); $q->enqueue( [ qw( a b c ) ] ); $q->enqueue( { a => 1, b => 2, c => 3 } ); is( $q->pending, 3, 'check number pending'); # dequeueing my @l= $q->dequeue; is( @l, 3, 'check # elements simple list' ); ok( ($l[0] eq 'a' and $l[1] eq 'b' and $l[2] eq 'c'), 'check simple list' ); my @lr= $q->dequeue_nb; cmp_ok( @lr, '==', 1, 'check # elements list ref' ); is( ref($lr[0]), 'ARRAY', 'check type of list ref' ); ok( ($lr[0]->[0] eq 'a' and $lr[0]->[1] eq 'b' and $lr[0]->[2] eq 'c'), 'check list ref' ); my @hr= $q->dequeue_keep; cmp_ok( @hr, '==', 1, 'check # elements hash ref, #1' ); is( ref($hr[0]), 'HASH', 'check type of hash ref, #1' ); ok( ($hr[0]->{a} == 1 and $hr[0]->{b} == 2 and $hr[0]->{c} == 3), 'check hash ref' ); @hr= $q->dequeue; cmp_ok( @hr, '==', 1, 'check # elements hash ref, #2' ); is( ref($hr[0]), 'HASH', 'check type of hash ref, #2' ); ok( ($hr[0]->{a} == 1 and $hr[0]->{b} == 2 and $hr[0]->{c} == 3), 'check hash ref' ); my @e= $q->dequeue_dontwait; cmp_ok( @e, '==', 0, 'check # elements non blocking' ); # serializer ok( eval "use $class serializer => 'Storable'; 1", "same serializer later" ); ok( !eval "use $class serializer => 'FrobNob'; 1", "different serializer" ); like( $@, qr#Cannot serialize with 'FrobNob', already using 'Storable'# ); ok( !eval "use $class freeze => sub {}; 1", "specific freeze" ); like( $@, qr#Cannot specify 'freeze', already using serializer 'Storable'# ); ok( !eval "use $class thaw => sub {}; 1", "specific thaw" ); like( $@, qr#Cannot specify 'thaw', already using serializer 'Storable'# ); ok( !eval "use $class frobnob => 1; 1", "unknown specification" ); like( $@, qr#Don't know what to do with: frobnob# ); done_testing(25); Thread-Queue-Any-1.17/t/010serializer.t0000644000175000017500000000356511761076120016554 0ustar rockyrockyBEGIN { # Magic Perl CORE pragma if ($ENV{PERL_CORE}) { chdir 't' if -d 't'; @INC = '../lib'; } } use strict; use warnings; my %Loaded; BEGIN { $Loaded{threads}= eval "use threads; 1"; $Loaded{forks}= eval "use forks; 1" if !$Loaded{threads}; } use Storable; use Thread::Queue::Any freeze => \&Storable::freeze, thaw => \&Storable::thaw, ;; use Test::More; diag "threads loaded" if $Loaded{threads}; diag "forks loaded" if $Loaded{forks}; ok( $Loaded{threads} || $Loaded{forks}, "thread-like module loaded" ); my $class= 'Thread::Queue::Any'; my $q= $class->new; isa_ok( $q, $class, 'check object type' ); # enqueing $q->enqueue( qw( a b c ) ); $q->enqueue( [ qw( a b c ) ] ); $q->enqueue( { a => 1, b => 2, c => 3 } ); is( $q->pending, 3, 'check number pending'); # dequeueing my $l= $q->dequeue; is( $l, 'a', 'check simple list in scalar context' ); my $lr= $q->dequeue_nb; is( ref($lr), 'ARRAY', 'check type of list ref' ); ok( ($lr->[0] eq 'a' and $lr->[1] eq 'b' and $lr->[2] eq 'c'), 'check list ref' ); my $hr= $q->dequeue_keep; is( ref($hr), 'HASH', 'check type of hash ref, #1' ); $hr= $q->dequeue; is( ref($hr), 'HASH', 'check type of hash ref, #2' ); ok( ($hr->{a} == 1 and $hr->{b} == 2 and $hr->{c} == 3), 'check hash ref' ); my $e= $q->dequeue_dontwait; ok( !defined($e), 'check empty' ); # serializer ok( !eval "use $class serializer => 'FrobNob'; 1", "different serializer" ); like( $@, qr#Cannot serialize with 'FrobNob', already using freeze/thaw# ); ok( !eval "use $class freeze => sub {}; 1", "specific freeze" ); like( $@, qr#Cannot specify new 'freeze', already using freeze/thaw# ); ok( !eval "use $class thaw => sub {}; 1", "specific thaw" ); like( $@, qr#Cannot specify new 'thaw', already using freeze/thaw# ); done_testing(16); Thread-Queue-Any-1.17/META.json0000644000175000017500000000173515000433645015147 0ustar rockyrocky{ "abstract" : "thread-safe queues for any data-structure", "author" : [ "Elizabeth Mattijsen (liz@dijkmat.nl)" ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.60, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "Thread-Queue-Any", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "Test::More" : "0.88", "Thread::Queue" : "0" } } }, "release_status" : "stable", "version" : "1.17", "x_serialization_backend" : "JSON::PP version 4.06" } Thread-Queue-Any-1.17/Makefile.PL0000644000175000017500000000144013654276475015514 0ustar rockyrockyrequire 5.008; use lib '.'; # do we have threads/forks? BEGIN { eval "use Devel::ThreadsForks; 1" || do 'threadsforks' } #BEGIN # make sure we have the right code path $LIB_TREE= 'Thread/Queue'; $REQUIRED= '5.014'; eval "use Devel::MaintBlead; 1" || do 'maintblead'; # set version and dependency info use ExtUtils::MakeMaker; eval "use Devel::Required maint_blead => $REQUIRED"; # set up prerequisites my @prereq_pm= ( 'Thread::Queue' => 0, ); push @prereq_pm, ( 'Test::More' => 0.88, ) if !$MAINT; # set up WriteMakefile ( NAME => 'Thread::Queue::Any', AUTHOR => 'Elizabeth Mattijsen (liz@dijkmat.nl)', ABSTRACT => 'thread-safe queues for any data-structure', VERSION_FROM => 'lib/Thread/Queue/Any.pm', LICENSE => 'perl', PREREQ_PM => { @prereq_pm }, ); Thread-Queue-Any-1.17/t_maint/0000755000175000017500000000000015000433645015153 5ustar rockyrockyThread-Queue-Any-1.17/t_maint/Queue-Any.t_maint0000644000175000017500000000274011760360640020347 0ustar rockyrockyBEGIN { # Magic Perl CORE pragma if ($ENV{PERL_CORE}) { chdir 't' if -d 't'; @INC = '../lib'; } } use strict; use warnings; use Test::More tests => 16; BEGIN { eval "use threads; 1" or eval "use forks; 1"; diag $@ if !ok( !$@, "threads or forks loaded ok" ); } BEGIN { use_ok('Thread::Queue::Any') } my $q = Thread::Queue::Any->new; isa_ok( $q, 'Thread::Queue::Any', 'check object type' ); can_ok( $q,qw( dequeue dequeue_dontwait dequeue_keep dequeue_nb enqueue new pending ) ); $q->enqueue( qw(a b c) ); $q->enqueue( [qw(a b c)] ); $q->enqueue( {a => 1, b => 2, c => 3} ); is( $q->pending, 3, 'check number pending'); my @l = $q->dequeue; is( @l, 3, 'check # elements simple list' ); ok( ($l[0] eq 'a' and $l[1] eq 'b' and $l[2] eq 'c'), 'check simple list' ); my @lr = $q->dequeue_nb; cmp_ok( @lr, '==', 1, 'check # elements list ref' ); is( ref($lr[0]), 'ARRAY', 'check type of list ref' ); ok( ($lr[0]->[0] eq 'a' and $lr[0]->[1] eq 'b' and $lr[0]->[2] eq 'c'), 'check list ref' ); my @hr = $q->dequeue_keep; cmp_ok( @hr, '==', 1, 'check # elements hash ref, #1' ); is( ref($hr[0]), 'HASH', 'check type of hash ref, #1' ); @hr = $q->dequeue; cmp_ok( @hr, '==', 1, 'check # elements hash ref, #2' ); is( ref($hr[0]), 'HASH', 'check type of hash ref, #2' ); ok( ($hr[0]->{a} == 1 and $hr[0]->{b} == 2 and $hr[0]->{c} == 3), 'check hash ref' ); my @e = $q->dequeue_dontwait; cmp_ok( @e, '==', 0, 'check # elements non blocking' ); Thread-Queue-Any-1.17/maintblead0000644000175000017500000001301212060402173015533 0ustar rockyrocky#------------------------------------------------------------------------------- # This file was auto-generated by Devel::MaintBlead 0.08 on # Fri Dec 7 16:00:11 2012. # can also be called from Devel::MaintBlead, we need the main:: package package main; # mark that we've run this (for testing mostly) $Devel::MaintBlead::SIZE= 5642; # huh? if ( !$LIB_TREE or !$REQUIRED ) { print STDERR <<'HUH'; Please make sure the global variables $LIB_TREE and $REQUIRED are set before using the Devel::MaintBlead module in your Makefile.PL. HUH exit 1; } # private initializations my @lib_tree= split "/", $LIB_TREE; $lib_tree[$_]= "$lib_tree[ $_ - 1 ]/$lib_tree[$_]" foreach 1 .. $#lib_tree; my @postfix= qw( blead maint ); my %maint= map { $postfix[$_] => $_ } 0 .. $#postfix; my $auto_maint= ( $] < $REQUIRED ) || 0; #------------------------------------------------------------------------------- # set up file moving primitive use File::Copy (); sub mv { if ( -e $_[1] ) { print STDERR <<"HUH"; Cowardly refusing to overwrite $_[1] from $_[0] This should not happen. Please advise the author of Devel::MaintBlead on how you managed to do this. Thank you! HUH exit 1; } return File::Copy::mv(@_); } #mv #------------------------------------------------------------------------------- # set up file moving logic # # IN: 1 "from" interpolation # 2 "to" interpolation # 3 lib_tree setting (default: $LIB_TREE) sub mv_all { my ( $from, $to, $lib_tree )= @_; # move generic files if ( !$lib_tree ) { mv "MANIFEST$from", "MANIFEST$to" or die "Could not move file MANIFEST$from -> $to: $!\n"; foreach ( map { m#/([^/\.]+\.t)$from$# } glob( "t$from/*$from" ) ) { mv "t$from/$_$from", "t$to/$_$to" or die "Could not move file t$from/$_$from -> $to: $!\n"; } # use the base lib_tree $lib_tree= $LIB_TREE; } # just make sure it exists else { mkdir "lib$to/$lib_tree"; } # move lib files here foreach ( map { m#/([^/\.]+\.pm)$from$# } glob( "lib$from/$lib_tree/*$from" ) ) { mv "lib$from/$lib_tree/$_$from", "lib$to/$lib_tree/$_$to" or die "Could not move file $lib$from/$lib_tree/$_$from -> $to: $!\n"; } # remove now possibly empty subdirectories rmdir "lib$from/$lib_tree" if $from; # move them there for all subdirs mv_all( $from, $to, "$lib_tree/$_" ) foreach map { m#/([^/]+)$# } grep { -d } glob "lib$from/$lib_tree/*"; } #mv_all #------------------------------------------------------------------------------- # unlink_all # # IN: 1 initial directory to remove files from sub unlink_all { my ($dir)= @_; # remove all files from this dir (don't care whether worked) unlink glob "$dir/*"; # recursively unlink all files in all directories unlink_all($_) foreach grep { -d } glob "$dir/*"; } #unlink_all #------------------------------------------------------------------------------- # first time running Makefile.PL if ( !-e 'pm_to_blib' ) { # set default setting $MAINT= !glob( "lib_$postfix[1]/$LIB_TREE/*" ) || 0; open( OUT, ">default" ); print OUT $postfix[$MAINT]; close OUT; } # extract override if there is one my $type; @ARGV= grep { defined $maint{$_} ? ( $type= $_, $MAINT= $maint{$_}, 0 ) : 1 } @ARGV; # we have an override if ($type) { print STDERR "Forcing to use the '$type' version of the code\n"; open( OUT, ">default" ); print OUT $postfix[$MAINT]; close OUT; } # get default setting if necessary else { open( IN, 'default' ); $MAINT= $maint{ }; close IN; } # sorry, we can't help you if ( $auto_maint and !$MAINT ) { # can't do blead, autoselect active, so go to maint if ( $ENV{AUTO_SELECT_MAINT_OR_BLEAD} ) { $MAINT=1; } # alas, can't do blead else { $REQUIRED= sprintf '%1.6f', $REQUIRED; print STDERR <<"SORRY"; This distribution requires at least Perl $REQUIRED to be installed. Since this is an older distribution, with a history spanning almost a decade, it is also available inside this distribution as a previous incarnation, which is actively maintained as well. You can install that version of this distribution by running this $0 with the additional "maint" parameter, like so: $^X $0 maint @ARGV Or you can provide an automatic selection behavior, which would automatically select and install the right version of this distribution for the version of Perl provided, by setting the AUTO_SELECT_MAINT_OR_BLEAD environment variable to a true value. On Unix-like systems like so: AUTO_SELECT_MAINT_OR_BLEAD=1 $^X $0 @ARGV Thank you for your attention. SORRY my $line= (caller)[2]; eval <<"BYEBYE" or print STDERR $@; #line $line $0 require $REQUIRED; BYEBYE exit 1; } } # create shortcuts my $this= $postfix[$MAINT]; my $that= $postfix[ !$MAINT ]; # make sure empty directories exist, 'make dist' doesn't include them foreach my $postfix (@postfix) { mkdir "lib_$postfix"; mkdir "lib_$postfix/$_" foreach @lib_tree; mkdir "t_$postfix"; } # need to move files into place if ( my @files= glob( "lib_$this/$LIB_TREE/*" ) ) { print STDERR "Moving $this files into position\n"; # move current files away mv_all( '', "_$that" ); # put files into place mv_all( "_$this", '' ); # make sure we will copy to blib unlink_all("blib/lib/$LIB_TREE/*"); } # right files already there else { print STDERR "Files for $this already in position\n"; } Thread-Queue-Any-1.17/threadsforks0000644000175000017500000000163111766010310016136 0ustar rockyrocky#------------------------------------------------------------------------------- # This file was auto-generated by Devel::ThreadsForks 0.06 on # Tue Jun 12 23:02:16 2012. # mark that we've run this (for testing mostly) $Devel::ThreadsForks::SIZE= 921; # get configuration information require Config; Config->import; # no ithreads and no forks if ( !$Config{useithreads} and !eval { require forks; 1 } ) { print STDERR <<"TEXT"; ************************************************************************ * This distribution requires a version of Perl that has threads enabled * or which has the forks.pm module installed. Unfortunately, this does * not appear to be the case for $^X. * * Please install a threaded version of Perl, or the "forks" module * before trying to install this distribution again. ************************************************************************ TEXT # byebye exit 1; } Thread-Queue-Any-1.17/README0000644000175000017500000000332612313562456014413 0ustar rockyrockyREADME for Thread::Queue::Any Almost drop-in replacement for Thread::Queue that allows any (unshared) data-structure to be passed between threads by means of a queue. *** A note of CAUTION *** This module only functions if threading has been enabled when building Perl, or if the "forks" module has been installed on an unthreaded Perl. ************************* Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Version: 1.14 Required Modules: Test::More (0.88) Thread::Queue (any) Installation: This distribution contains two versions of the code: one maintenance version for versions of perl < 5.014 (known as 'maint'), and the version currently in development (known as 'blead'). The standard build for your perl version is: perl Makefile.PL make make test make install This will try to test and install the "blead" version of the code. If the Perl version does not support the "blead" version, then the running of the Makefile.PL will *fail*. In such a case, one can force the installing of the "maint" version of the code by doing: perl Makefile.PL maint Alternately, if you want automatic selection behavior, you can set the AUTO_SELECT_MAINT_OR_BLEAD environment variable to a true value. On Unix-like systems like so: AUTO_SELECT_MAINT_OR_BLEAD=1 perl Makefile.PL If your perl does not support the "blead" version of the code, then it will automatically install the "maint" version of the code. Please note that any additional parameters will simply be passed on to the underlying Makefile.PL processing. Thread-Queue-Any-1.17/META.yml0000644000175000017500000000113115000433645014765 0ustar rockyrocky--- abstract: 'thread-safe queues for any data-structure' author: - 'Elizabeth Mattijsen (liz@dijkmat.nl)' build_requires: ExtUtils::MakeMaker: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.60, CPAN::Meta::Converter version 2.150010' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Thread-Queue-Any no_index: directory: - t - inc requires: Test::More: '0.88' Thread::Queue: '0' version: '1.17' x_serialization_backend: 'CPAN::Meta::YAML version 0.018' Thread-Queue-Any-1.17/lib_maint/0000755000175000017500000000000015000433645015456 5ustar rockyrockyThread-Queue-Any-1.17/lib_maint/Thread/0000755000175000017500000000000015000433645016665 5ustar rockyrockyThread-Queue-Any-1.17/lib_maint/Thread/Queue/0000755000175000017500000000000015000433645017751 5ustar rockyrockyThread-Queue-Any-1.17/lib_maint/Thread/Queue/Any.pm_maint0000644000175000017500000001321012060403203022211 0ustar rockyrockypackage Thread::Queue::Any; # initializations @ISA= qw( Thread::Queue ); $VERSION= '0.16'; # be as strict as possble use strict; # modules that we need use Storable (); # no need to pollute namespace use Thread::Queue (); # no need to pollute namespace # synonym for dequeue_dontwait { no warnings 'once'; *dequeue_nb = \&dequeue_dontwait; } # satisfy -require- 1; #------------------------------------------------------------------------------- # IN: 1 instantiated object # 2..N parameters to be passed as a set onto the queue sub enqueue { return shift->SUPER::enqueue( Storable::freeze( \@_ ) ); } #enqueue #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue { return @{ Storable::thaw( shift->SUPER::dequeue ) }; } #dequeue #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue_dontwait { my $ref= shift->SUPER::dequeue_nb or return; return @{ Storable::thaw($ref) }; } #dequeue_dontwait #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue_keep { lock( @{ $_[0] } ); # make sure we're the only my $ref= shift->[0] or return; return @{ Storable::thaw($ref) }; } #dequeue_keep #------------------------------------------------------------------------------- __END__ =head1 NAME Thread::Queue::Any - thread-safe queues for any data-structure =head1 SYNOPSIS use Thread::Queue::Any; my $q= Thread::Queue::Any->new; $q->enqueue("foo", ["bar"], {"zoo"}); my ( $foo, $bar, $zoo )= $q->dequeue; my ( $foo, $bar, $zoo )= $q->dequeue_dontwait; my ( $iffoo, $ifbar, $ifzoo)= $q->dequeue_keep; my $left= $q->pending; =head1 VERSION This documentation describes version 0.16. =head1 DESCRIPTION *** A note of CAUTION *** This module only functions on threaded perl or an unthreaded perl with the "forks" module installed. Please also note that this documentation describes the "maint" version of this code. This version is essentially frozen. Please use a 5.14 or higher version of perl for the "blead" version of this code. ************************* A queue, as implemented by C is a thread-safe data structure that inherits from C. But unlike the standard C, you can pass (a reference to) any data structure to the queue. Apart from the fact that the parameters to C are considered to be a set that needs to be enqueued together and that C returns all of the parameters that were enqueued together, this module is a drop-in replacement for C in every other aspect. Any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. (Queues don't permit adding or removing elements from the middle of the list). =head1 CLASS METHODS =head2 new $queue= Thread::Queue::Any->new; The C function creates a new empty queue. =head1 OBJECT METHODS =head2 enqueue LIST $queue->enqueue( 'string', $scalar, [], {} ); The C method adds a reference to all the specified parameters on to the end of the queue. The queue will grow as needed. =head2 dequeue ( $string, $scalar, $listref, $hashref )= $queue->dequeue; The C method removes a reference from the head of the queue, dereferences it and returns the resulting values. If the queue is currently empty, C will block the thread until another thread Cs. =head2 dequeue_dontwait ( $string, $scalar, $listref, $hashref )= $queue->dequeue_dontwait; The C method, like the C method, removes a reference from the head of the queue, dereferences it and returns the resulting values. Unlike C, though, C won't wait if the queue is empty, instead returning an empty list if the queue is empty. For compatibility with L, the name "dequeue_nb" is available as a synonym for this method. =head2 dequeue_keep ( $string, $scalar, $listref, $hashref )= $queue->dequeue_keep; The C method, like the C method, takes a reference from the head of the queue, dereferences it and returns the resulting values. Unlike C, though, the C B the set from the queue. It can therefore be used to test if the next set to be returned from the queue with C or C will have a specific value. =head2 pending $pending= $queue->pending; The C method returns the number of items still in the queue. =head1 REQUIRED MODULES Thread::Queue (any) =head1 CAVEATS Passing unshared values between threads is accomplished by serializing the specified values using C when enqueuing and de-serializing the queued value on dequeuing. This allows for great flexibility at the expense of more CPU usage. It also limits what can be passed, as e.g. code references can B be serialized and therefore not be passed. =head1 AUTHOR Elizabeth Mattijsen, . Please report bugs to . =head1 COPYRIGHT Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L, L, L. =cut Thread-Queue-Any-1.17/TODO0000644000175000017500000000022310050423634014202 0ustar rockyrockyCheck out whether Data::Dumper as an alternate way to safely serialize data (including code refs) between threads, as per suggestion of Brent Dax. Thread-Queue-Any-1.17/CHANGELOG0000644000175000017500000002044013654276775014760 0ustar rockyrocky0.16 5 May 2020 Exit early in the Makefile if on an unthreadable perl 0.15 9 November 2019 Adopted 1.14 23 March 2014 Upgraded to Thread::Queue 3.*, as part of Perl 5.18.*. 1.13 7 December 2012 Upgraded to Devel::MaintBlead 0.08. This should fix the problem as reported in https://rt.cpan.org/Ticket/Display.html?id=81354 by Justin Traer. Also upgraded the maint version to 0.16. 1.12 4 June 2012 Upgraded to Devel::ThreadsForks 0.05 and Devel::MaintBlead 0.04. Also upgraded the maint version to 0.15. 1.11 2 June 2012 Fixed problem in serializer specification. Found while working on Thread::Queue::Any::Monitored subclass. 1.10 2 June 2012 Added "THAW" class method for subclasses such as Thread::Queue::Any::Monitored. 1.09 2 June 2012 Updated "maintblead" to Devel::MaintBlead 0.02. This should fix the problem that if an inappropriate Perl version was seen, the Makefile.PL would not exit. Also updated "threadsforks" to Devel::ThreadsForks 0.02. 1.08 1 June 2012 No functional changes apart from the whole maint/blead logic now being handled by the new Devel::MaintBlead module, rather than being hardcoded in here. 1.07 1 June 2012 Added installation description (as generated by the latest version of Devel::Required) to pod and README. The experiment by generating a "maint" distribution has worked out ok. Both releases are now viewable on search.cpan.org and MetaCPAN. The only thing I need to do, is upload the "maint" distribution before the "blead" version. Added logic so that the very *first* time Makefile.PL is run, it does not try to move the "blead" version of the code into place. This will make the "maint" distribution do the right thing. Upped the "maint" version to 0.14, so that it works better than the 0.13 (which tries to install "blead" anyway). 1.06 31 May 2012 Replaced forks/threads checking logic in Makefile.PL by using the new Devel::ThreadsForks module. Changed order of files in MANIFEST in the hope that it will show the "blead" version of the module by default in search.cpan.org. Changed erroneous "require 5.014" by more appropriate "use 5.014". 1.05 30 May 2012 After on/offlist discussion on p5p, I decided to not have automatic state selection logic. Instead, it will by default try to install the "blead" version of the code and fail with an extensive message if the version of Perl is not sufficient. This should ensure "normal" behavior as a distribution with a Perl version restriction, while at the same time allow packagers to install / package the "maint" version without too much trouble. Reverted the order in which files were moved into place. This was done to prevent warnings about missing files when doing a running of perl Makefile.PL maint from scratch. The better solution is just to have a MANIFEST_maint file as well, and move that into place before ExtUtils::MakeMaker does its manifest check. There are no functional differences in the code otherwise. 1.04 29 May 2012 It appears that Devel::Required was deleting the extra text with the version information. Instead I now changed the "A note of caution" message. Moved the moving files into position code until *after* the Makefile has been written. This should take care of missing files from MANIFEST warnings when calling perl Makefile.PL for the "maint" version for the first time. Apparently the MANIFEST check is only done the very first time Makefile.PL is being run. Which is a good thing. Raised the maint version to 0.13. 1.03 29 May 2012 Apparently I lost the pod explaining that the maint version of the code is the maint version. Added again. For some reason, both versions of the code show up on search.cpan.org. Then it is good to show that that documentation does not describe the real thing (anymore). The "dequeue*" methods now return the first element of the values in scalar context. This should simplify the most often used use case, where only one value is passed to "enqueue". As suggested in RT #74560. 1.02 29 May 2012 ARGH DOUBLE ARGH. MetaCPAN appears to dislike the new -package- format so much still, that the occurrence of it, will put the whole distribution into a black hole. Sigh. Also: from a previous way that I implemented multiple versions of the code, a "make distclean" would clean up too much. Now fixed. Added serializer tests. 1.01 29 May 2012 ARGH. "package name version" still not being understood by PAUSE or MetaCPAN. Reverting to setting $VERSION explicitely. 1.00 29 May 2012 Raised version to 1.00, to more easily recognize maintenance versions of the module from the more modern version. Added mention if being the maint version in the source of the maint version. The maint version should now be considered to be frozen, except for serious bug fixes. Added code version parameter to Makefile.PL and documented this in the README file. Changed tests as suggested by Michael Schwern in RT #76810. Added support for other serializer, such as suggested in RT #58250. Sorry it had to take this long! No tests yet, but the documentation is at least there already. 0.12 28 May 2012 It appears that PAUSE is indexing the last file it finds when trying to determine what to index. So I renamed the "lib_blead" directory to "lib_xblead" so that it will sort after "lib_maint". This should cause PAUSE to index the blead version of the code, rather than the maint version. 0.11 27 May 2012 Added LICENSE setting. Introduced the concept of a "maint" and a "blead" version of the code, so that it is possible to start using new Perl features for newer versions of the code. This means that for versions of perl <5.14, the "maint" version of the code will be installed (0.10), whereas for the perl versions >=5.14, the "blead" version will be installed (0.11). There are no other differences between the versions yet, this is really just a test to see how PAUSE and (search.|meta)cpan cope with this. 0.10 1 April 2012 Some code refactoring and code esthetics. Fixed problem in test-suite. Verified it runs on 5.14.2. 0.09 3 October 2007 Hopefully fixed test-suite for non-thread enabled Perls. 0.08 3 August 2007 Added version markers so that there will be no complaining if Devel::Required is installed. Otherwise same as 0.07. 0.07 28 December 2003 Added automatic required modules update using Devel::Required. 0.06 13 August 2003 Cleaned up Makefile.PL and updated copyright info. Made sure the test-suite runs ok with warnings enabled. Removed our and ":unique" attribute as with all of my other Thread::xxx modules. 0.05 24 July 2002 Made $VERSION and @ISA have the : unique attribute to save memory. Added method "dequeue_keep" plus documentation and test-suite. 0.04 21 July 2002 Added "can_ok" check to the test-suite. Renamed "dequeue_nb" to "dequeue_dontwait" to be more in line with Thread::Pool. Added "dequeue_nb" as synonym to remain compatible with Thread::Queue. Fixed several documentation nits. 0.03 14 July 2002 Added -use threads- to Makefile.PL to cause breakage if attempting to install on a system without threads. Added Perl version requirement to README and pod per suggestion of mrbbking. 0.02 13 July 2002 Added copyright info to pod. Name change threads::shared:: -> Thread:: caused this module to be renamed to Thread::Queue::Any. And all the other changes that were necessary. 0.01 10 July 2002 First version of threads::shared::queue::any. Thread-Queue-Any-1.17/lib/0000755000175000017500000000000015000433645014266 5ustar rockyrockyThread-Queue-Any-1.17/lib/Thread/0000755000175000017500000000000015000433645015475 5ustar rockyrockyThread-Queue-Any-1.17/lib/Thread/Queue/0000755000175000017500000000000015000433645016561 5ustar rockyrockyThread-Queue-Any-1.17/lib/Thread/Queue/Any.pm0000644000175000017500000003034615000433631017647 0ustar rockyrockyuse 5.014; #package Thread::Queue::Any '1.17'; # not supported by PAUSE or MetaCPAN :-( package Thread::Queue::Any; # please remove if no longer needed # initializations our @ISA= qw( Thread::Queue ); our $VERSION= '1.17'; # please remove if no longer needed # be as verbose as possble use warnings; # modules that we need use Thread::Queue (); # no need to pollute namespace BEGIN { *ISHASH = sub () { $Thread::Queue::VERSION >= 3 } } # synonym for dequeue_dontwait { no warnings 'once'; *dequeue_nb = \&dequeue_dontwait; } # thread local settings my $SERIALIZER; my $FREEZE; my $THAW; # satisfy -require- 1; #------------------------------------------------------------------------------- # # Class methods # #------------------------------------------------------------------------------- # IN: 1 class (not used) # OUT: 1 code ref used for thawing sub THAW { $THAW } #THAW #------------------------------------------------------------------------------- # # Instance methods # #------------------------------------------------------------------------------- # IN: 1 instantiated object # 2..N parameters to be passed as a set onto the queue sub enqueue { return shift->SUPER::enqueue( $FREEZE->( \@_ ) ); } #enqueue #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue { return wantarray ? @{ $THAW->( shift->SUPER::dequeue ) } : $THAW->( shift->SUPER::dequeue )->[0]; } #dequeue #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue_dontwait { my $ref= shift->SUPER::dequeue_nb or return; return wantarray ? @{ $THAW->($ref) } : $THAW->($ref)->[0]; } #dequeue_dontwait #------------------------------------------------------------------------------- # IN: 1 instantiated object # OUT: 1..N parameters returned from a set on the queue sub dequeue_keep { # make sure we're the only one lock( ISHASH ? $_[0] : @{ $_[0] } ); my $ref= ( ISHASH ? shift->{queue}->[0] : shift->[0] ) or return; return wantarray ? @{ $THAW->($ref) } : $THAW->($ref)->[0]; } #dequeue_keep #------------------------------------------------------------------------------- # # Standard Perl features # #------------------------------------------------------------------------------- # IN: 1 class (not used) # 2 .. N parameter hash sub import { my ( undef, %param )= @_; my @errors; # parameters we know my $serializer= delete $param{serializer}; my $freeze= delete $param{freeze}; my $thaw= delete $param{thaw}; # sanity check with serializer class if ($serializer) { push @errors, "Cannot serialize with '$serializer', already using '$SERIALIZER'" if $SERIALIZER and $serializer ne $SERIALIZER; push @errors, "Cannot serialize with '$serializer', already using freeze/thaw" if !$SERIALIZER and ( $FREEZE or $THAW ); push @errors, "Cannot specify 'freeze', already using serializer '$serializer'" if $freeze; push @errors, "Cannot specify 'thaw', already using serializer '$serializer'" if $thaw; } # sanity if no serializer, but just freeze / thaw elsif ($freeze) { push @errors, "Cannot specify 'freeze', already using serializer '$SERIALIZER'" if $SERIALIZER; push @errors, "Cannot specify new 'freeze', already using freeze/thaw" if !$SERIALIZER and $FREEZE; push @errors, "Must also specify 'thaw' if specifying 'freeze'" if !$thaw; } # sanity if no serializer or freeze, but with thaw elsif ($thaw) { push @errors, "Cannot specify 'thaw', already using serializer '$SERIALIZER'" if $SERIALIZER; push @errors, "Cannot specify new 'thaw', already using freeze/thaw" if !$SERIALIZER and $THAW; } # huh? if ( my @huh= keys %param ) { push @errors, "Don't know what to do with: @huh"; } die join "\n", "Found the following errors:", @errors if @errors; # found specific serializer if ($serializer) { _set_serializer($serializer); } # found separate freeze/thaw subs elsif ($freeze) { $FREEZE= $freeze; $THAW= $thaw; } # use default serializer else { _set_serializer('Storable'); } return; } #import #------------------------------------------------------------------------------- # # Internal subroutines # #------------------------------------------------------------------------------- # _set_serializer # # IN: 1 class sub _set_serializer { my ($class)= @_; # sanity check my @errors; eval "require $class; 1" or push @errors, $@; my $freeze= $class->can( 'freeze' ) or push @errors, "$class does not provide a 'freeze' method"; my $thaw= $class->can( 'thaw' ) or push @errors, "$class does not provide a 'thaw' method"; # huh? die join "\n", "Found the following errors:", @errors if @errors; # it's all ok $SERIALIZER= $class; $FREEZE= $freeze; $THAW= $thaw; return; } #_set_serializer #------------------------------------------------------------------------------- __END__ =head1 NAME Thread::Queue::Any - thread-safe queues for any data-structure =head1 SYNOPSIS use Thread::Queue::Any; my $q= Thread::Queue::Any->new; $q->enqueue("foo", ["bar"], {"zoo"}); my ( $foo, $bar, $zoo )= $q->dequeue; my ( $foo, $bar, $zoo )= $q->dequeue_dontwait; my ( $iffoo, $ifbar, $ifzoo)= $q->dequeue_keep; my $left= $q->pending; # specify class with "freeze" and "thaw" methods use Thread::Queue::Any serializer => 'Storable'; # specify custom freeze and thaw subroutines use Thread::Queue::Any freeze => \&solid, thaw => \&liquid; # thaw hook for subclasses package Thread::Queue::Any::Foo; @ISA= 'Thread::Queue::Any'; my $THAW= __PACKAGE__->THAW; =head1 VERSION This documentation describes version 1.17. =head1 DESCRIPTION *** A note of CAUTION *** This module only functions if threading has been enabled when building Perl, or if the "forks" module has been installed on an unthreaded Perl. ************************* A queue, as implemented by C is a thread-safe data structure that inherits from C. But unlike the standard C, you can pass (a reference to) any data structure to the queue. Apart from the fact that the parameters to C are considered to be a set that needs to be enqueued together and that C returns all of the parameters that were enqueued together, this module is a drop-in replacement for C in every other aspect. Any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. =head1 CLASS METHODS =head2 new $queue= Thread::Queue::Any->new; The C function creates a new empty queue. =head2 THAW $THAW= $subclass->THAW; Return the code reference for de-serializing enqueued data. Intended to be used by subclasses only, such as L. =head1 OBJECT METHODS =head2 enqueue LIST $queue->enqueue( 'string', $scalar, [], {} ); The C method adds a reference to all the specified parameters on to the end of the queue. The queue will grow as needed. =head2 dequeue ( $string, $scalar, $listref, $hashref )= $queue->dequeue; $string= $queue->dequeue; # first only in scalar context The C method removes a reference from the head of the queue, dereferences it and returns the resulting values. If the queue is currently empty, C will block the thread until another thread Cs. If called in scalar context, only the first value will be returned. This is only recommended if L is always only called with one parameter. =head2 dequeue_dontwait ( $string, $scalar, $listref, $hashref )= $queue->dequeue_dontwait; $string= $queue->dequeue_dontwait; # first only in scalar context The C method, like the C method, removes a reference from the head of the queue, dereferences it and returns the resulting values. Unlike C, though, C won't wait if the queue is empty, instead returning an empty list if the queue is empty. For compatibility with L, the name "dequeue_nb" is available as a synonym for this method. If called in scalar context, only the first value will be returned. This is only recommended if L is always only called with one parameter. =head2 dequeue_keep ( $string, $scalar, $listref, $hashref )= $queue->dequeue_keep; $string= $queue->dequeue_keep; # first only in scalar context The C method, like the C method, takes a reference from the head of the queue, dereferences it and returns the resulting values. Unlike C, though, the C B the set from the queue. It can therefore be used to test if the next set to be returned from the queue with C or C will have a specific value. If called in scalar context, only the first value will be returned. This is only recommended if L is always only called with one parameter. =head2 pending $pending= $queue->pending; The C method returns the number of items still in the queue. =head1 USING ANOTHER SERIALIZER Passing unshared values between threads is accomplished by serializing the specified values when enqueuing and de-serializing the queued value on equeuing. This allows for great flexibility at the expense of more CPU usage. It also limits what can be passed, as e.g. code references can B be serialized with the default serializer and therefore not be passed. By default, the L module is used to serialize data. If you want to use a different serializer, you can specify this when you load this module with the C parameter: use Thread::Queue::Any serializer => 'Thread::Serialize'; The value of the parameter is the name of the class that will provide a C and C subroutine. It will be automatically loaded if specified. If you happen to have subroutines in another module with a different name, you can also specify the C and C parameter with a code reference of the subroutine to be called. So the above example could also be specified as: use Thread::Serialize; use Thread::Queue::Any freeze => \&Thread::Serialize::freeze, thaw => \&Thread::Serialize::thaw, ; =head1 REQUIRED MODULES Test::More (0.88) Thread::Queue (any) =head1 INSTALLATION This distribution contains two versions of the code: one maintenance version for versions of perl < 5.014 (known as 'maint'), and the version currently in development (known as 'blead'). The standard build for your perl version is: perl Makefile.PL make make test make install This will try to test and install the "blead" version of the code. If the Perl version does not support the "blead" version, then the running of the Makefile.PL will *fail*. In such a case, one can force the installing of the "maint" version of the code by doing: perl Makefile.PL maint Alternately, if you want automatic selection behavior, you can set the AUTO_SELECT_MAINT_OR_BLEAD environment variable to a true value. On Unix-like systems like so: AUTO_SELECT_MAINT_OR_BLEAD=1 perl Makefile.PL If your perl does not support the "blead" version of the code, then it will automatically install the "maint" version of the code. Please note that any additional parameters will simply be passed on to the underlying Makefile.PL processing. =head1 AUTHOR Elizabeth Mattijsen, . Maintained by LNATION Please report bugs to . =head1 COPYRIGHT Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen . 2025 LNATION All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L, L, L. =cut Thread-Queue-Any-1.17/MANIFEST_maint0000644000175000017500000000064511763120047016047 0ustar rockyrockyMANIFEST MANIFEST_blead CHANGELOG README TODO Makefile.PL lib/Thread/Queue/Any.pm lib_blead/Thread/Queue/Any.pm_blead t/Queue-Any.t t_blead/001basic.t_blead t_blead/010serializer.t_blead META.yml Module meta-data (added by MakeMaker) threadsforks threads/forks test (Added by Devel::ThreadsForks) maintblead maint/blead test (added by Devel::MaintBlead)