document threads support
authorTony Cook <tony@develop-help.com>
Sat, 18 Aug 2012 00:20:44 +0000 (10:20 +1000)
committerTony Cook <tony@develop-help.com>
Sat, 25 Aug 2012 03:04:08 +0000 (13:04 +1000)
Imager.pm
MANIFEST
lib/Imager/Threads.pod [new file with mode: 0644]

index 71af068..399a209 100644 (file)
--- a/Imager.pm
+++ b/Imager.pm
@@ -4363,6 +4363,10 @@ L<Imager::ExtUtils> - tools to get access to Imager's C API.
 
 L<Imager::Security> - brief security notes.
 
+=item *
+
+L<Imager::Threads> - brief information on working with threads.
+
 =back
 
 =head2 Basic Overview
@@ -4804,6 +4808,8 @@ text, wrapping text in an area - L<Imager::Font::Wrap>
 
 text, measuring - L<Imager::Font/bounding_box()>, L<Imager::Font::BBox>
 
+threads - L<Imager::Threads>
+
 tiles, color - L<Imager::Filters/mosaic>
 
 transparent images - L<Imager::ImageTypes>,
@@ -4817,15 +4823,6 @@ watermark - L<Imager::Filters/watermark>
 
 writing an image to a file - L<Imager::Files>
 
-=head1 THREADS
-
-Imager doesn't support perl threads.
-
-Imager has limited code to prevent double frees if you create images,
-colors etc, and then create a thread, but has no code to prevent two
-threads entering Imager's error handling code, and none is likely to
-be added.
-
 =head1 SUPPORT
 
 The best place to get help with Imager is the mailing list.
index 9880063..9549a1c 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -200,6 +200,7 @@ lib/Imager/regmach.pod
 lib/Imager/Regops.pm
 lib/Imager/Security.pod
 lib/Imager/Test.pm
+lib/Imager/Threads.pod
 lib/Imager/Transform.pm
 lib/Imager/Transformations.pod
 lib/Imager/Tutorial.pod
diff --git a/lib/Imager/Threads.pod b/lib/Imager/Threads.pod
new file mode 100644 (file)
index 0000000..7defd84
--- /dev/null
@@ -0,0 +1,64 @@
+=head1 NAME
+
+Imager::Threads - Imager and threads
+
+=head1 SYNOPSIS
+
+  use Imager;
+  use threads;
+  Imager->preload;
+
+  threads->create(...);
+
+=head1 DESCRIPTION
+
+Starting from version 0.93 Imager attempts to work safely with perl's
+C<ithreads>.
+
+Previous versions stored some state in global variables, in particular
+the internal error stack.
+
+However there are some limitations:
+
+=over
+
+=item *
+
+Imager's debug malloc isn't thread safe and will never be.  Imager's
+debug malloc is disabled by default.
+
+=item *
+
+C<libtiff>, which Imager uses for TIFF file support is not thread
+safe, C<Imager::File::TIFF> works around this by single-threading its
+access to C<libtiff>.
+
+=item *
+
+C<giflib>, which Imager uses for GIF support is not thread safe before
+version 5.  C<Imager::File::GIF> works around this by single threading
+its access to C<giflib>.
+
+=item *
+
+killing a thread reading or writing TIFF or GIF files may deadlock
+other threads when they attempt to read or write TIFF or GIF files.
+
+=back
+
+Note that if you have another module using C<libtiff> or C<giflib> it
+may interact with Imager's use of those libraries in a threaded
+environment, since there's no way to co-ordinate access to the global
+information C<libtiff> and C<giflib> maintain.
+
+Imager currently doesn't use threads itself.
+
+=head1 SEE ALSO
+
+Imager, C<threads>
+
+=head1 AUTHOR
+
+Tony Cook <tony@cpan.org>
+
+=cut