dist/Thread-Queue - add missing build artifacts

Add Changes, Makefile.PL and examples directory.

Fixes this module for https://github.com/Perl/perl5/issues/20874

5 files changed, 300 insertions, 0 deletions

diff --git a/dist/Thread-Queue/.gitignore b/dist/Thread-Queue/.gitignore
new file mode 100644
index 0000000000..e54624d60d
--- /dev/null
+++ b/dist/Thread-Queue/.gitignore
@@ -0,0 +1 @@
+!/Makefile.PL
diff --git a/dist/Thread-Queue/Changes b/dist/Thread-Queue/Changes
new file mode 100644
index 0000000000..c41c77ada0
--- /dev/null
+++ b/dist/Thread-Queue/Changes
@@ -0,0 +1,79 @@
+Revision history for Perl extension Thread::Queue.
+
+3.13 Wed Jul 18 02:00:03 2018
+	- [rt.cpan.org #125868] Fix tests for Test::Simple 1.302138
+
+3.12 Thu Feb  9 18:42:45 2017
+	- Fix deadlock caused by combination of dequeue_nb, enqueue and
+		queue size limit (Bug #120157 - fix by Chad Fox)
+	- Prevent calling dequeue methods with COUNT > LIMIT
+
+3.11 Fri May 20 18:33:00 2016
+	- Removed use of detached threads in tests (Bug #114468)
+
+3.09 Sat Apr 30 21:33:54 2016
+	- Sync with blead
+
+3.07 Fri Oct 23 23:54:18 2015
+	- Edge-case fix to queue limit feature
+
+3.06 Sat Aug 22 20:33:23 2015
+	- Added queue limit feature as per suggestion by Mark Zealey
+
+3.05 Thu Mar 20 21:39:32 2014
+	- Sync with blead
+
+3.04 Tue Mar 11 19:29:00 2014
+	- Fix for reporting correct location of validation error
+
+3.03 Thu Mar  6 20:50:41 2014
+	- Conversion of internal functions to methods to permit sub-classing
+
+3.02 Tue Feb 19 18:22:15 2013
+	- Timed dequeue as per suggestion by Andreas Huber
+
+3.01 Tue Oct 23 22:44:30 EDT 2012
+	- Added ->end() as per suggestion by Michael G. Schwern
+	- Major version bump because of change in structure of queue objects
+
+2.12 Fri Dec 24 17:52:51 2010
+	- Install in 'site' for Perl >= 5.011
+	- Test file changes for core
+	- Added new example (examples/callback.pl) to distribution
+	- POD update
+
+2.11 Thu Jun 12 13:41:45 2008
+	- End all tests with exit(0) and fix SKIPs
+
+2.09 Fri May 30 16:31:48 2008
+	- Check for 'undef' for counts and indices
+
+2.08 Wed May 14 15:24:53 2008
+	- Use threads::shared::shared_clone() for complex data
+
+2.07 Wed May  7 18:48:46 2008
+	- Properly clone complex structures with circular references
+
+2.06 Fri Feb 22 22:08:38 2008
+	- Allow installation on non-threaded Perls
+
+2.05 Wed Feb 20 17:21:25 2008
+	- Build/test updates
+
+2.04 Mon Feb 18 12:31:30 2008
+	- Install under 'perl' dir
+
+2.03 Fri Feb 15 18:54:15 2008
+	- Support queuing refs of refs
+
+2.02 Fri Feb 15 15:18:11 2008
+	- Fix tests to work under Perl 5.8.0
+
+2.01 Thu Feb 14 18:11:00 2008
+	- Added 'count' option to dequeue and dequeue_nb
+	- Added peek, insert and extract methods
+	- Support queuing of complex data structures
+
+2.00 Jul 12 16:31:00 2002
+	- Released as part of Perl 5.8.0
+
diff --git a/dist/Thread-Queue/Makefile.PL b/dist/Thread-Queue/Makefile.PL
new file mode 100644
index 0000000000..9828dd669f
--- /dev/null
+++ b/dist/Thread-Queue/Makefile.PL
@@ -0,0 +1,41 @@
+# Module makefile for Thread::Queue (using ExtUtils::MakeMaker)
+
+require 5.008;
+
+use strict;
+use warnings;
+
+use ExtUtils::MakeMaker;
+
+# Construct make file
+WriteMakefile(
+    'NAME'          => 'Thread::Queue',
+    'AUTHOR'        => 'Jerry D. Hedden <jdhedden AT cpan DOT org>',
+    'VERSION_FROM'  => 'lib/Thread/Queue.pm',
+    'ABSTRACT_FROM' => 'lib/Thread/Queue.pm',
+    'PREREQ_PM'     => {
+        'threads::shared'   => 1.21,
+        'Scalar::Util'      => 1.10,
+        'Test::More'        => 0.50,
+        'Thread::Semaphore' => 0,
+    },
+    'INSTALLDIRS'   => (($] < 5.011) ? 'perl' : 'site'),
+
+    ((ExtUtils::MakeMaker->VERSION() lt '6.25') ?
+        ('PL_FILES' => { })            : ()),
+    ((ExtUtils::MakeMaker->VERSION() gt '6.30') ?
+        ('LICENSE'  => 'perl_5')       : ()),
+);
+
+# Additional 'make' targets
+sub MY::postamble
+{
+    return <<'_EXTRAS_';
+fixfiles:
+	@dos2unix `cat MANIFEST`
+	@$(CHMOD) 644 `cat MANIFEST`
+	@$(CHMOD) 755 examples/*.pl
+_EXTRAS_
+}
+
+# EOF
diff --git a/dist/Thread-Queue/examples/callback.pl b/dist/Thread-Queue/examples/callback.pl
new file mode 100755
index 0000000000..43c0084d33
--- /dev/null
+++ b/dist/Thread-Queue/examples/callback.pl
@@ -0,0 +1,123 @@
+#!/usr/bin/perl
+
+# Simplified example illustrating event handling and callback threads
+
+# Callback threads register their queues with the event handler thread.
+# Events are passed to the event handler via a queue.
+# The event handler then disseminates the event to the appropriately
+#   registered thread.
+
+use strict;
+use warnings;
+
+use threads;
+use Thread::Queue;
+
+MAIN:
+{
+    # Queue for registering callbacks
+    my $regis_q = Thread::Queue->new();
+
+    # Queue for disseminating events
+    my $event_q = Thread::Queue->new();
+
+    # Create callback threads
+    threads->create('CallBack', 'USR1', $regis_q)->detach();
+    threads->create('CallBack', 'USR2', $regis_q)->detach();
+    threads->create('CallBack', 'HUP', $regis_q)->detach();
+    threads->create('CallBack', 'ALRM', $regis_q)->detach();
+
+    # Create event handler thread
+    threads->create('EventHandler', $regis_q, $event_q)->detach();
+
+    # Capture SIGUSR1 events
+    $SIG{'USR1'} = sub {
+        $event_q->enqueue('USR1');  # Send to event handler
+    };
+
+    # Capture SIGUSR1 events
+    $SIG{'USR2'} = sub {
+        $event_q->enqueue('USR2');  # Send to event handler
+    };
+
+    # Capture SIGHUP events
+    $SIG{'HUP'} = sub {
+        $event_q->enqueue('HUP');  # Send to event handler
+    };
+
+    # Capture SIGHUP events
+    $SIG{'ALRM'} = sub {
+        $event_q->enqueue('ALRM');  # Send to event handler
+        alarm(5);                   # Reset alarm
+    };
+
+    # Ready
+    print(<<_MSG_);
+Send signals to PID = $$
+  (e.g., 'kill -USR1 $$')
+Use ^C (or 'kill -INT $$') to terminate
+_MSG_
+
+    # Set initial alarm
+    alarm(5);
+
+    # Just hang around
+    while (1) {
+        sleep(10);
+    }
+}
+
+### Subroutines ###
+
+sub EventHandler
+{
+    my ($regis_q, $event_q) = @_;
+
+    my %callbacks;   # Registered callback queues
+
+    while (1) {
+        # Check for any registrations
+        while (my ($event_type, $q) = $regis_q->dequeue_nb(2)) {
+            if ($q) {
+                $callbacks{$event_type} = $q;
+            } else {
+                warn("BUG: Bad callback registration for event type $event_type\n");
+            }
+        }
+
+        # Wait for event
+        if (my $event = $event_q->dequeue()) {
+            # Send event to appropriate queue
+            if (exists($callbacks{$event})) {
+                $callbacks{$event}->enqueue($event);
+            } else {
+                warn("WARNING: No callback for event type $event\n");
+            }
+        }
+    }
+}
+
+
+sub CallBack
+{
+    my $event_type = shift;   # The type of event I'm handling
+    my $regis_q    = shift;
+
+    # Announce registration
+    my $tid = threads->tid();
+    print("Callback thread $tid registering for $event_type events\n");
+
+    # Register my queue for my type of event
+    my $q = Thread::Queue->new();
+    $regis_q->enqueue($event_type, $q);
+
+    # Process loop
+    while (1) {
+        # Wait for event callback
+        my $item = $q->dequeue();
+        # Process event
+        print("Callback thread $tid notified of $item event\n") if $item;
+    }
+}
+
+# EOF
diff --git a/dist/Thread-Queue/examples/queue.pl b/dist/Thread-Queue/examples/queue.pl
new file mode 100755
index 0000000000..dc818fd488
--- /dev/null
+++ b/dist/Thread-Queue/examples/queue.pl
@@ -0,0 +1,56 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+use threads;
+use Thread::Queue 3.01;
+
+# Create a work queue for sending data to a 'worker' thread
+#   Prepopulate it with a few work items
+my $work_q = Thread::Queue->new(qw/foo bar baz/);
+
+# Create a status queue to get reports from the thread
+my $status_q = Thread::Queue->new();
+
+# Create a detached thread to process items from the queue
+threads->create(sub {
+                    # Keep grabbing items off the work queue
+                    while (defined(my $item = $work_q->dequeue())) {
+                        # Process the item from the queue
+                        print("Thread got '$item'\n");
+
+                        # Ask for more work when the queue is empty
+                        if (! $work_q->pending()) {
+                            print("\nThread waiting for more work\n\n");
+                            $status_q->enqueue('more');
+                        }
+                    }
+
+                    # Final report
+                    print("Thread done\n");
+                    $status_q->enqueue('done');
+
+                })->detach();
+
+# More work for the thread
+my @work = (
+    [ 'bippity', 'boppity', 'boo' ],
+    [ 'ping', 'pong' ],
+    [ 'dit', 'dot', 'dit' ],
+);
+
+# Send work to the thread
+while ($status_q->dequeue() eq 'more') {
+    last if (! @work);   # No more work
+    $work_q->enqueue(@{shift(@work)});
+}
+
+# Signal that there is no more work
+$work_q->end();
+# Wait for thread to terminate
+$status_q->dequeue();
+# Good-bye
+print("Done\n");
+
+# EOF