Author: timbo
Date: Mon Jul 26 01:40:03 2010
New Revision: 14283
Modified:
dbi/trunk/Changes
dbi/trunk/DBI.pm
dbi/trunk/DBIXS.h
dbi/trunk/dbixs_rev.h
Log:
Updates to r14282 prior to actual implementation
Fixed flag bit. Made attribute inherited. Tweaked docs.
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Mon Jul 26 01:40:03 2010
@@ -6,6 +6,11 @@
=cut
+=head2 Changes in DBI 1.614 (svn rXXX) XXX 2010
+
+ Added $h->{AutoInactiveDestroy} as simpler safer form of
+ $h->{InactiveDestroy} (David E. Wheeler)
+
=head2 Changes in DBI 1.613 (svn r14271) 22nd July 2010
Fixed Win32 prerequisite module from PathTools to File::Spec.
Modified: dbi/trunk/DBI.pm
==============================================================================
--- dbi/trunk/DBI.pm (original)
+++ dbi/trunk/DBI.pm Mon Jul 26 01:40:03 2010
@@ -107,6 +107,9 @@
archives and read the DBI FAQ. The archives are listed
at the end of this document and on the DBI home page.
+You might also like to read the Advanced DBI Tutorial at
+L<http://www.slideshare.net/Tim.Bunce/dbi-advanced-tutorial-2007>
+
This document often uses terms like I<references>, I<objects>,
I<methods>. If you're not familiar with those terms then it would
be a good idea to read at least the following perl manuals first:
@@ -3615,20 +3618,21 @@
If set true then the handle will be treated by the DESTROY as if it was no
longer Active, and so the I<database engine> related effects of DESTROYing a
-handle will be skipped.
-
-Think of the name as meaning 'treat the handle as not-Active in the DESTROY
-method'.
+handle will be skipped. Think of the name as meaning 'treat the handle as
+not-Active in the DESTROY method'.
For a database handle, this attribute does not disable an I<explicit>
call to the disconnect method, only the implicit call from DESTROY
that happens if the handle is still marked as C<Active>.
This attribute is specifically designed for use in Unix applications
-that "fork" child processes. Either the parent or the child process,
-but not both, should set C<InactiveDestroy> true on all their shared handles.
-(Note that some databases, including Oracle, don't support passing a
-database connection across a fork.)
+that "fork" child processes. For some drivers, when the child process exits
+the destruction of inherited handles cause the corresponding handles in the
+perent process to cease working.
+
+Either the parent or the child process, but not both, should set
+C<InactiveDestroy> true on all their shared handles. Alternatively the
+L</AutoInactiveDestroy> can be set in the parent on connect.
To help tracing applications using fork the process id is shown in
the trace log whenever a DBI or handle trace() method is called.
@@ -3638,31 +3642,24 @@
=head3 C<AutoInactiveDestroy>
-Type: boolean
+Type: boolean, inherited
+
+The L</InactiveDestroy> attribute, described above, needs to be explicitly set
+in the child process after a fork(). This is a problem if the code that
performs
+the fork() is not under your control, perhaps in a third-party module.
+Use C<AutoInactiveDestroy> to get around this situation.
-While its best to set C<InactiveDestroy> on a handle when you've C<fork>ed off
-a child process, sometimes you might call code that C<fork>s without your
-knowledge. In such a case, if a the child exits and then the parent tries to
-use the original handle, it might fail, as the child might have closed the
-socket the parent was using.
-
-Use C<AutoInactiveDestroy> to get around this situation. Like
-C<InactiveDestroy>, when set to a true value the handle will be treated by the
-DESTROY as if it was no longer Active, and so the I<database engine> related
-effects of DESTROYing a handle will be skipped. This only happens, however, if
-the DBI detects that the process ID in which the handle is being DESTROYed is
-different than the process ID in which it was created.
+If set true, the DESTROY method will check the process id of the handle and, if
+different from the current process id, it will set the I<InactiveDestroy>
attribute.
This is the example it's designed to deal with:
my $dbh = DBI->connect(...);
- some_code_that_forks(); # Perhaps without your knowlege.
- $dbh->do(...); # dies.
+ some_code_that_forks(); # Perhaps without your knowledge
+ # Child process dies, destroying the inherited dbh
+ $dbh->do(...); # Breaks because parent $dbh is now broken
-The issue is that C<$dbh> is DESTROYed in the fork and closes the socket from
-the parent, too. Pass a true value for C<AutoInactiveDestroy> and the DBI will
-automatically detect when a forked database handle is being DESTROYed and
-treat the handle as non-active.
+The C<AutoInactiveDestroy> attribute was added in DBI 1.614.
=head3 C<PrintWarn>
Modified: dbi/trunk/DBIXS.h
==============================================================================
--- dbi/trunk/DBIXS.h (original)
+++ dbi/trunk/DBIXS.h Mon Jul 26 01:40:03 2010
@@ -244,7 +244,6 @@
#define DBIcf_IMPSET 0x000002 /* has implementor data to be clear'd
*/
#define DBIcf_ACTIVE 0x000004 /* needs finish/disconnect before
clear */
#define DBIcf_IADESTROY 0x000008 /* do DBIc_ACTIVE_off before DESTROY
*/
-#define DBIcf_AIADESTROY 0x000009 /* autod DBIc_ACTIVE_off before
DESTROY */
#define DBIcf_WARN 0x000010 /* warn about poor practice etc
*/
#define DBIcf_COMPAT 0x000020 /* compat/emulation mode (eg oraperl)
*/
#define DBIcf_ChopBlanks 0x000040 /* rtrim spaces from fetch char
columns */
@@ -263,10 +262,11 @@
#define DBIcf_Executed 0x080000 /* do/execute called since
commit/rollb */
#define DBIcf_PrintWarn 0x100000 /* warn() on warning (err="0")
*/
#define DBIcf_Callbacks 0x200000 /* has Callbacks attribute hash
*/
+#define DBIcf_AIADESTROY 0x400000 /* auto DBIcf_IADESTROY if pid changes
*/
/* NOTE: new flags may require clone() to be updated */
#define DBIcf_INHERITMASK /* what NOT to pass on to children */
\
- (U32)( DBIcf_COMSET | DBIcf_IMPSET | DBIcf_ACTIVE | DBIcf_IADESTROY |
DBIcf_AIADESTROY \
+ (U32)( DBIcf_COMSET | DBIcf_IMPSET | DBIcf_ACTIVE | DBIcf_IADESTROY \
| DBIcf_AutoCommit | DBIcf_BegunWork | DBIcf_Executed | DBIcf_Callbacks )
/* general purpose bit setting and testing macros */
Modified: dbi/trunk/dbixs_rev.h
==============================================================================
--- dbi/trunk/dbixs_rev.h (original)
+++ dbi/trunk/dbixs_rev.h Mon Jul 26 01:40:03 2010
@@ -1,3 +1,3 @@
-/* Sun Jul 25 16:30:05 2010 */
+/* Mon Jul 26 09:35:19 2010 */
/* Code modified since last checkin */
-#define DBIXS_REVISION 14281
+#define DBIXS_REVISION 14282
