Merge pull request #967 from fglock/docs/thread-release-gates

docs: deliver permanent Perl thread release gates

Author: fglock

.github/workflows/gradle.yml

@@ -41,6 +41,25 @@ jobs:
         if: runner.os == 'Linux'
         run: make ci
 
+      - name: Checkout pinned Perl thread compatibility corpus
+        if: runner.os == 'Linux'
+        uses: actions/checkout@v4
+        with:
+          repository: Perl/perl5
+          ref: de80c8ecd40c6d5b677847699e5482b44bc748c6
+          path: perl5
+          sparse-checkout: |
+            t
+            dist/threads
+            dist/threads-shared
+            dist/Thread-Queue
+            dist/Thread-Semaphore
+
+      - name: Run Perl thread compatibility gate
+        if: runner.os == 'Linux'
+        timeout-minutes: 20
+        run: make test-threads
+
       - name: Generate SBOM (Linux only)
         if: runner.os == 'Linux'
         run: make sbom
@@ -59,4 +78,6 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: test-results-${{ matrix.os }}
-          path: build/reports/tests/test/
+          path: |
+            build/reports/tests/test/
+            build/reports/threads/

Makefile

@@ -1,4 +1,26 @@
-.PHONY: all clean test test-unit test-interpreter test-bundled-modules test-cpan-distroprefs test-exiftool test-all test-gradle test-gradle-unit test-gradle-all test-gradle-parallel test-maven-parallel build run wrapper check-java-gradle dev ci sbom sbom-java sbom-perl sbom-clean check-links
+.PHONY: all clean test test-unit test-interpreter check-thread-test-sources test-threads test-threads-release test-bundled-modules test-cpan-distroprefs test-exiftool test-all test-gradle test-gradle-unit test-gradle-all test-gradle-parallel test-maven-parallel build run wrapper check-java-gradle dev ci sbom sbom-java sbom-perl sbom-clean check-links
+
+THREAD_DIST_DIRS := perl5/dist/threads/t perl5/dist/threads-shared/t perl5/dist/Thread-Queue/t perl5/dist/Thread-Semaphore/t
+THREAD_PLATFORM_TESTS := \
+	perl5/dist/threads/t/end.t \
+	perl5/dist/threads/t/exit.t \
+	perl5/dist/threads/t/free.t \
+	perl5/dist/threads/t/free2.t \
+	perl5/dist/threads/t/join.t \
+	perl5/dist/threads/t/kill.t \
+	perl5/dist/threads/t/kill2.t \
+	perl5/dist/threads/t/kill3.t \
+	perl5/dist/threads/t/stack.t \
+	perl5/dist/threads/t/stack_env.t \
+	perl5/dist/threads/t/state.t \
+	perl5/dist/threads/t/zz_deadlock.t \
+	perl5/dist/threads-shared/t/cond.t \
+	perl5/dist/threads-shared/t/wait.t \
+	perl5/dist/threads-shared/t/waithires.t \
+	perl5/dist/Thread-Queue/t/09_ended.t \
+	perl5/dist/Thread-Queue/t/10_timed.t \
+	perl5/dist/Thread-Semaphore/t/04_nonblocking.t \
+	perl5/dist/Thread-Semaphore/t/06_timed.t
 
 all: build
 
@@ -87,6 +109,35 @@ test-interpreter:
 	@echo "Running unit tests with bytecode interpreter..."
 	JPERL_INTERPRETER=1 perl dev/tools/perl_test_runner.pl --jobs 8 --timeout 60 --output test_interpreter_results.json src/test/resources/unit
 
+# Verify the unchanged upstream test distributions are available. GitHub CI
+# sparse-checks them out at the compatibility-corpus commit recorded below;
+# local developers normally use their adjacent/gitignored perl5 source tree.
+check-thread-test-sources:
+	@for dir in $(THREAD_DIST_DIRS); do \
+		if [ ! -d "$$dir" ]; then \
+			echo "Error: $$dir is missing."; \
+			echo "Clone Perl commit de80c8ecd40c6d5b677847699e5482b44bc748c6 into ./perl5 before running the thread gates."; \
+			exit 1; \
+		fi; \
+	done
+
+# Permanent Perl ithread compatibility gate used by Ubuntu pull-request CI.
+# Full upstream distributions run on both backends with the default virtual
+# carrier; lifecycle, stack, signal, wait, timeout, and deadlock coverage also
+# runs on the platform carrier. Reports are retained under build/reports/threads.
+test-threads: check-java-gradle check-thread-test-sources
+	@mkdir -p build/reports/threads
+	JPERL_THREAD_MODE=virtual perl dev/tools/perl_test_runner.pl --strict-exit --jobs 8 --timeout 300 --output build/reports/threads/jvm-virtual.json $(THREAD_DIST_DIRS)
+	JPERL_INTERPRETER=1 JPERL_THREAD_MODE=virtual perl dev/tools/perl_test_runner.pl --strict-exit --jobs 8 --timeout 300 --output build/reports/threads/interpreter-virtual.json $(THREAD_DIST_DIRS)
+	JPERL_THREAD_MODE=platform perl dev/tools/perl_test_runner.pl --strict-exit --jobs 8 --timeout 300 --output build/reports/threads/platform-focused.json $(THREAD_PLATFORM_TESTS)
+
+# Thread release gate: extend the PR gate to the complete platform-carrier
+# distribution matrix. Together with test-threads this covers both backends on
+# both carrier policies without making every pull request repeat all four runs.
+test-threads-release: test-threads
+	JPERL_THREAD_MODE=platform perl dev/tools/perl_test_runner.pl --strict-exit --jobs 8 --timeout 300 --output build/reports/threads/jvm-platform.json $(THREAD_DIST_DIRS)
+	JPERL_INTERPRETER=1 JPERL_THREAD_MODE=platform perl dev/tools/perl_test_runner.pl --strict-exit --jobs 8 --timeout 300 --output build/reports/threads/interpreter-platform.json $(THREAD_DIST_DIRS)
+
 # Bundled CPAN module tests (XML::Parser, etc.)
 # Tests live under src/test/resources/module/{ModuleName}/t/
 test-bundled-modules: check-java-gradle

dev/design/concurrency.md

@@ -1,7 +1,7 @@
 # Perl Threads Implementation Plan
 
-**Status:** Active implementation plan
-**Version:** 2.2
+**Status:** Delivered; compatibility maintenance
+**Version:** 3.0
 **Date:** 2026-08-15
 
 ## 1. Goal and Non-Negotiable Delivery Rule
@@ -222,13 +222,13 @@ direct companions.
 ## 6. Supporting Design Contracts
 
 - `dev/design/attributes.md` defines the supported `shared` attribute surface.
-- `dev/design/runtime-pooling-reset-contract.md` defines the proof required
-  before runtime pooling can be enabled.
+- `dev/design/runtime-pooling-reset-contract.md` defines the implemented
+  bounded pool reset and fresh-runtime replacement contract.
 - `dev/design/phase36-regex-parity.md` owns direct regex-language and Joni work.
 
 ## 7. Progress Tracking
 
-### Current Status: release validation in progress; Joni/regex parity is separate
+### Current Status: delivered; Joni/regex parity is separate
 
 `PerlRuntime` owns interpreter state, ithreads clone one isolated runtime graph,
 and `threads::shared` supplies explicit cross-runtime storage and synchronization.
@@ -246,19 +246,21 @@ requests.
 
 ### Next Steps
 
-1. Finish the local release gates: `make`, documentation links, all four
-   upstream distribution configurations, the thread preservation matrix,
-   and `timeout 3600 ./jcpan --jobs 8 -t DBIx::Class`.
-2. Review the final diff for temporary diagnostics, generated files, accidental
-   upstream-test edits, and any mutable runtime state lacking an ownership
-   classification.
-3. Open the pull request with the exact gate results in its commit messages and
-   description.
-4. Require green Ubuntu and Windows CI. Investigate and fix any CI failure on
-   the branch; do not merge on a rerun-only explanation.
-5. After merge, treat the four unchanged upstream distributions as permanent
-   regression gates. Continue direct regex-language work, including Joni, only
-   in the separate Phase 36 project.
+1. Keep `make test-threads` as a permanent Ubuntu pull-request gate. It runs
+   both execution backends with virtual carriers and focused platform lifecycle,
+   signal, stack, wait, timeout, and deadlock coverage.
+2. Run `make test-threads-release` before any thread/runtime release. It extends
+   the pull-request gate to the complete four-module matrix on platform carriers.
+3. Continue CPAN ecosystem hardening: opt-in Test2 stress tests, remaining Moose
+   thread-suite classification, Net::SSLeay callback suites 61/62, and permanent
+   DBI ownership plus DBIx::Class release coverage.
+4. Require every future native resource, I/O handle, and callback adapter to
+   declare its runtime ownership, snapshot, aliasing, and close policy.
+5. Monitor snapshot retention and startup cost. Runtime pooling remains bounded,
+   opt-in, and disabled by default; returned application runtimes are replaced,
+   not partially reused.
+6. Keep direct regex-language and Joni work in the separate Phase 36 project.
+   Threaded regex wrappers must preserve their same-commit direct behavior.
 
 Direct regex-language work, including Joni integration, is not part of this
 release.
@@ -278,6 +280,7 @@ relative to their same-commit direct companions.
 ## Related Documents
 
 - `dev/design/attributes.md` — current attribute behavior
-- `dev/design/runtime-pooling-reset-contract.md` — required proof before pooling
+- `dev/design/runtime-pooling-reset-contract.md` — bounded pooling and
+  fresh-runtime replacement contract
 - `dev/design/phase36-regex-parity.md` — independent regex parity project
 - `dev/design/fork_open_emulation.md` — process/fork-related alternatives

dev/tools/perl_test_runner.pl

@@ -18,12 +18,14 @@
 my $jobs = 5;     # Default to 5 parallel jobs
 my $output_file;
 my $help;
+my $strict_exit = 0;
 
 GetOptions(
     'jperl=s'   => \$jperl_path,
     'timeout=f' => \$timeout,
     'jobs|j=i'  => \$jobs,
     'output=s'  => \$output_file,
+    'strict-exit!' => \$strict_exit,
     'help'      => \$help,
 ) or die "Error in command line arguments\n";
 
@@ -113,6 +115,12 @@
     save_results($output_file);
 }
 
+if ($strict_exit
+        && ($summary{fail} || $summary{error} || $summary{timeout}
+            || $summary{incomplete})) {
+    exit 1;
+}
+
 # Subroutines
 
 sub find_test_files {
@@ -239,6 +247,12 @@ sub process_test_result {
     print " " x (50 - length($rel_path)) if length($rel_path) < 50;
     printf " ... %s %d/%d ok (%.2fs)\n",
         $char, $result->{ok_count}, $result->{total_tests}, $duration;
+    if ($result->{status} ne 'pass' && defined $result->{failure_output}) {
+        print "----- captured output: $rel_path -----\n";
+        print $result->{failure_output};
+        print "\n" unless $result->{failure_output} =~ /\n\z/;
+        print "----- end captured output -----\n";
+    }
 }
 
 # Single, clean run_single_test function
@@ -475,6 +489,11 @@ sub run_single_test {
 
     my $result = parse_tap_output($output, $exit_code);
     $result->{raw_output_path} = $raw_output_path;
+    # Preserve a bounded diagnostic tail in the JSON report and CI log.  Raw
+    # output normally lives in /tmp on the worker and disappears before an
+    # uploaded report can be inspected.
+    $result->{failure_output} = substr($output, -32768)
+        if $result->{status} ne 'pass';
     return $result;
 }
 
@@ -504,6 +523,8 @@ sub timeout_for_test {
 sub requires_exclusive_slot {
     my ($test_file) = @_;
     return $test_file =~ m{
+          (?:^|/)perl5/dist/threads/t/join\.t$
+        |
           (?:^|/)perl5_t/t/op/gv\.t$
         | (?:^|/)perl5_t/t/re/pat(?:_thr)?\.t$
         | (?:^|/)perl5_t/t/re/pat_psycho(?:_thr)?\.t$
@@ -820,6 +841,7 @@ sub print_usage {
                    subprocess-heavy tests have a documented minimum)
   --jobs|-j NUM    Number of parallel jobs (default: 5)
   --output FILE    Save detailed results to JSON file
+  --strict-exit    Exit nonzero if any file fails, errors, times out, or is incomplete
   --help           Show this help message
 
 Examples:

docs/README.md

@@ -30,7 +30,7 @@ Technical reference documentation:
 - **[Bundled Modules](reference/bundled-modules.md)** - Complete list of included modules
 - **[XS Compatibility](reference/xs-compatibility.md)** - XS modules and Java implementations
 - **[CLI Options](reference/cli-options.md)** - Command-line reference
-- **[Concurrency](reference/feature-matrix.md#concurrency-and-perl-threads)** - Multiplicity, ithreads, shared storage, and limitations
+- **[Perl Threads](reference/threads.md)** - Ithreads, shared storage, carrier policy, resources, and testing
 - **[Runtime Configuration](reference/configure.md#runtime-thread-configuration)** - Thread capability flags and execution mode
 - **[Memory Management](reference/memory-management.md)** - JVM GC, deterministic destruction, weak references, and threads
 - **[Testing](reference/testing.md)** - Test suite information

docs/about/changelog.md

@@ -8,7 +8,7 @@ Release history of PerlOnJava. See [Roadmap](roadmap.md) for future plans.
   manifest, provide a JAXP-backed `XML::LibXSLT`, and preserve descriptors for
   anonymous handles stored in container lvalues. This unblocks
   `Catmandu::CrossRef` and `AnyEvent::SMTP` without distribution preferences.
-- Add Perl interpreter multiplicity and the supported ithread tranche across
+- Add Perl interpreter multiplicity and full ithread support across
   the JVM and interpreter backends. Mutable execution state is owned by
   independent `PerlRuntime` instances; child threads receive identity-aware
   snapshots, while `threads::shared` preserves explicitly shared
@@ -22,9 +22,11 @@ Release history of PerlOnJava. See [Roadmap](roadmap.md) for future plans.
   registrations retain their owning runtime, internal pipes have an explicit
   inherited-handle policy, and nested plain shared graphs are validated before
   publication. General resource inheritance, DBI ownership, lexical regex
-  diagnostics, blessed roots, and tied shared-value conversion are implemented;
-  exact nested shared-reference proxies remain limited;
-  see the [feature matrix](../reference/feature-matrix.md#concurrency-and-perl-threads).
+  diagnostics, blessed roots, tied shared-value conversion, nested shared
+  proxy views, and global final destruction are implemented. The unchanged
+  upstream `threads`, `threads::shared`, `Thread::Queue`, and
+  `Thread::Semaphore` distributions pass on both backends and both Java carrier
+  policies; see the [Perl threads reference](../reference/threads.md).
 - CPAN/tooling: expose tested dependency scripts through `PATH`, deduplicate
   repeated `PERL5LIB` setup, and resolve test prerequisites against tested
   `blib` trees before launching tests. Add `JSON::DWIW`, `Taint::Runtime`, and

docs/about/roadmap.md

@@ -46,10 +46,10 @@ These capabilities are implemented and available in the current release:
 - **I/O Subsystem** — Sockets, I/O layers (`:raw`, `:utf8`, `:crlf`, `:encoding()`), in-memory files, pipes, file descriptor duplication, `flock`, tied handles.
 - **Multiplicity and Perl ithreads** — Mutable interpreter state is owned by
   `PerlRuntime`; `Config` advertises `useithreads`, `usethreads`, and
-  `usemultiplicity`. The supported `threads` and `threads::shared` tranche
-  includes isolated create/join, shared scalar/array/hash storage, recursive
-  locks, and condition variables on both backends. See the
-  [feature matrix](../reference/feature-matrix.md#concurrency-and-perl-threads).
+  `usemultiplicity`. The bundled `threads`, `threads::shared`, `Thread::Queue`,
+  and `Thread::Semaphore` distributions pass unchanged on both backends and
+  both Java carrier policies. See the
+  [Perl threads reference](../reference/threads.md).
 - **Pack/Unpack** — Full template support for binary data manipulation. See `dev/design/pack_unpack_architecture.md`.
 - **Subroutine Prototypes and Signatures** — All prototype characters supported; formal parameter signatures implemented.
 - **`format`/`write`** — Report generation with `formline` and `$^A` accumulator.
@@ -259,17 +259,17 @@ Introduce a normalization pass between parsing and code generation to eliminate
 
 ## Objective 6: Concurrency & Runtime Isolation
 
-*Priority: Long-term — Major architectural work required.*
+*Priority: Maintenance and ecosystem hardening.*
 
 See `dev/design/concurrency.md` for the comprehensive design covering multiplicity, fork emulation, and threads.
 
 ### Multiplicity
 
-Multiple independent `PerlRuntime` instances and snapshot cloning are now
-implemented. Remaining work is compatibility hardening: close the applicable
-core/CPAN thread-suite gaps, prove native callback isolation, and define a
-reset contract before considering runtime pooling. Multiplicity alone does not
-make one JSR-223 engine or one captured PSGI app concurrently callable.
+Multiple independent `PerlRuntime` instances and snapshot cloning are
+implemented. The bounded PSGI runtime pool is opt-in and replaces returned app
+snapshots from an authoritative template; it does not partially reset and reuse
+an entered runtime. Multiplicity alone does not make one JSR-223 engine or one
+captured PSGI app concurrently callable.
 
 ### Fork Emulation
 
@@ -281,18 +281,18 @@ Implement `fork()` via runtime cloning + thread. Currently returns `undef`.
 
 ### Threads (ithreads)
 
-The supported ithread tranche is shipped: snapshot-based variable isolation,
-create/join/detach and lifecycle inspection, nested threads and child exit,
-`threads::shared` storage, recursive locks, and condition variables. Java 24
-virtual threads are the default; platform carriers remain selectable.
+Perl ithreads are shipped: snapshot-based variable isolation, lifecycle and
+signals, nested threads and child exit, `threads::shared` graphs and proxies,
+locks and conditions, `Thread::Queue`, and `Thread::Semaphore`. Java 24 virtual
+threads are the default; platform carriers remain selectable.
 
 Remaining work:
 
-- Complete the currently partial applicable core and regex suites.
-- Finish exact nested-reference proxy identity and global `DESTROY` ownership
-  for blessed values fetched through `threads::shared` aggregates. Root
-  blessed storage and the system-Perl tied conversion rules are implemented.
-- Keep runtime pooling disabled until the reset-equivalence contract is proven.
+- Keep the permanent PR and release matrices green.
+- Broaden CPAN/native ecosystem coverage, including opt-in Test2 and Moose
+  thread suites and Net::SSLeay callback stress.
+- Keep direct regex-language/Joni work in the separate Phase 36 project while
+  thread wrappers preserve the behavior of their direct companions.
 
 ---
 

docs/reference/cli-options.md

@@ -227,6 +227,7 @@ JPERL_OPTS='-Djperl.thread.mode=platform' ./jperl threaded.pl
 The carrier selection does not change Perl snapshot or shared-storage
 semantics. A nonzero per-thread stack request automatically selects a platform
 carrier because virtual-thread stacks are JVM-managed. See the
+[Perl threads reference](threads.md) and
 [concurrency feature matrix](feature-matrix.md#concurrency-and-perl-threads).
 
 ### Runtime pooling

docs/reference/configure.md

@@ -29,7 +29,8 @@ module reports the shipped runtime capabilities directly:
 Java 24 virtual threads are the launcher default. The platform executor remains
 available process-wide with `JPERL_THREAD_MODE=platform` or the JVM property
 `-Djperl.thread.mode=platform`. Unknown values are rejected. See
-[CLI Options](cli-options.md#thread-execution-mode) and the
+[CLI Options](cli-options.md#thread-execution-mode), the
+[Perl threads reference](threads.md), and the
 [feature matrix](feature-matrix.md#concurrency-and-perl-threads).
 
 Runtime pooling is independently opt-in. `JPERL_RUNTIME_POOL_SIZE=N` (or