document FCGI tied handle problem and workaround

dagolden · Feb 13, 2012 · ff773a1 · ff773a1
1 parent 9630b78
commit ff773a1
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 10 deletions.
diff --git a/Changes b/Changes
@@ -2,6 +2,12 @@ Revision history for Capture-Tiny
 
 {{$NEXT}}
 
+  Documented:
+
+  - Noted problems and workaround for FCGI's pathological tied STDIN
+    [rt.cpan.org #74681; thank you Karl Gaissmaier for testing the
+    workaround]
+
 0.15      2011-12-23 11:10:47 EST5EDT
 
   Fixed:

diff --git a/META.json b/META.json
@@ -4,7 +4,7 @@
       "David Golden <dagolden@cpan.org>"
    ],
    "dynamic_config" : 1,
-   "generated_by" : "Dist::Zilla version 4.300003, CPAN::Meta::Converter version 2.112580",
+   "generated_by" : "Dist::Zilla version 4.300005, CPAN::Meta::Converter version 2.112621",
    "license" : [
       "apache_2_0"
    ],
@@ -55,7 +55,7 @@
    "provides" : {
       "Capture::Tiny" : {
          "file" : "lib/Capture/Tiny.pm",
-         "version" : "0.15"
+         "version" : "0.16"
       }
    },
    "release_status" : "stable",
@@ -71,6 +71,6 @@
          "web" : "https://github.com/dagolden/capture-tiny"
       }
    },
-   "version" : "0.15"
+   "version" : "0.16"
 }
 
diff --git a/README.pod b/README.pod
@@ -6,7 +6,7 @@ Capture::Tiny - Capture STDOUT and STDERR from Perl, XS or external programs
 
 =head1 VERSION
 
-version 0.15
+version 0.16
 
 =head1 SYNOPSIS
 
@@ -194,7 +194,7 @@ output handle after the capture is complete.  (Requires Perl 5.8)
 Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar
 reference.
 
-B<Tied handles>
+B<Tied output handles>
 
 If STDOUT or STDERR are tied prior to the call to C<<< capture >>> or C<<< tee >>>, then
 Capture::Tiny will attempt to override the tie for the duration of the
@@ -207,8 +207,28 @@ is based on L<Tie::StdHandle>, then Capture::Tiny will attempt to determine
 appropriate layers like C<<< :utf8 >>> from the underlying handle and do the right
 thing.
 
-Capture::Tiny attempts to preserve the semantics of tied STDIN, but capturing
-or teeing when STDIN is tied is currently broken on Windows.
+B<Tied input handle>
+
+Capture::Tiny attempts to preserve the semantics of tied STDIN, but this is not
+entirely stable or portable. For example:
+
+=over
+
+=item *
+
+Capturing or teeing with STDIN tied is broken on Windows
+
+=item *
+
+L<FCGI> has been reported as having a pathological tied handle implementation
+that causes fatal (and hard to diagnose) errors
+
+=back
+
+Unless having STDIN tied is crucial, it may be safest to localize STDIN when
+capturing:
+
+   my ($out, $err) = do { local *STDIN; capture { ... } };
 
 =head2 Modifying handles during a capture
 

diff --git a/lib/Capture/Tiny.pm b/lib/Capture/Tiny.pm
@@ -586,7 +586,7 @@ output handle after the capture is complete.  (Requires Perl 5.8)
 Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar
 reference.
 
-*Tied handles*
+*Tied output handles*
 
 If STDOUT or STDERR are tied prior to the call to {capture} or {tee}, then
 Capture::Tiny will attempt to override the tie for the duration of the
@@ -599,8 +599,19 @@ is based on [Tie::StdHandle], then Capture::Tiny will attempt to determine
 appropriate layers like {:utf8} from the underlying handle and do the right
 thing.
 
-Capture::Tiny attempts to preserve the semantics of tied STDIN, but capturing
-or teeing when STDIN is tied is currently broken on Windows.
+*Tied input handle*
+
+Capture::Tiny attempts to preserve the semantics of tied STDIN, but this is not
+entirely stable or portable. For example:
+
+* Capturing or teeing with STDIN tied is broken on Windows
+* [FCGI] has been reported as having a pathological tied handle implementation
+that causes fatal (and hard to diagnose) errors
+
+Unless having STDIN tied is crucial, it may be safest to localize STDIN when
+capturing:
+
+  my ($out, $err) = do { local *STDIN; capture { ... } };
 
 == Modifying handles during a capture