>From 1443145b0302189fc7964562d39b7c422fc60ff9 Mon Sep 17 00:00:00 2001
From: Richard Jones <rjones@redhat.com>
Date: Thu, 10 Jun 2010 12:14:41 +0100
Subject: [PATCH] perl: Add explicit close() method (RHBZ#602592).

This add an optional explicit $g->close method which may be
used to force the handle to be closed immediately.  Note the
provisos about this method in the manual page entry.  Callers
should *not* normally use this method.

This commit also adds a regression test.

This commit also changes the existing warning when you call
a method without a Sys::Guestfs handle as the first parameter,
into an error.  This is because such cases are always errors.
---
 perl/t/800-explicit-close.t |   51 +++++++++++++++++++++++++++++++++++++++++++
 perl/typemap                |    9 ++++---
 src/generator.ml            |   31 ++++++++++++++++++++++++++
 3 files changed, 87 insertions(+), 4 deletions(-)
 create mode 100644 perl/t/800-explicit-close.t

diff --git a/perl/t/800-explicit-close.t b/perl/t/800-explicit-close.t
new file mode 100644
index 0000000..8185168
--- /dev/null
+++ b/perl/t/800-explicit-close.t
@@ -0,0 +1,51 @@
+# libguestfs Perl bindings -*- perl -*-
+# Copyright (C) 2010 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+# Test implicit vs explicit closes of the handle (RHBZ#602592).
+
+use strict;
+use warnings;
+use Test::More tests => 10;
+
+use Sys::Guestfs;
+
+my $g;
+
+$g = Sys::Guestfs->new ();
+ok($g);
+$g->close ();                   # explicit close
+ok($g);
+undef $g;                       # implicit close - should be no error/warning
+ok(1);
+
+# Expect an error if we call a method on a closed handle.
+$g = Sys::Guestfs->new ();
+ok($g);
+$g->close ();
+ok($g);
+eval { $g->set_memsize (512); };
+ok($g);
+ok($@ && $@ =~ /closed handle/);
+undef $g;
+ok(1);
+
+# Try calling a method without a blessed reference.  This should
+# give a different error.
+eval { Sys::Guestfs::set_memsize (undef, 512); };
+ok ($@ && $@ =~ /not.*blessed/);
+eval { Sys::Guestfs::set_memsize (42, 512); };
+ok ($@ && $@ =~ /not.*blessed/);
diff --git a/perl/typemap b/perl/typemap
index 752ca0d..6a018a2 100644
--- a/perl/typemap
+++ b/perl/typemap
@@ -6,11 +6,12 @@ int64_t	  	T_IV
 
 INPUT
 O_OBJECT_guestfs_h
-    if (sv_isobject ($arg) && SvTYPE (SvRV ($arg)) == SVt_PVMG)
+    if (sv_isobject ($arg) && SvTYPE (SvRV ($arg)) == SVt_PVMG) {
         $var = ($type) SvIV ((SV *) SvRV ($arg));
-    else {
-        warn (\"${Package}::$func_name(): $var is not a blessed SV reference\");
-        XSRETURN_UNDEF;
+        if ($var == NULL)
+            croak (\"${Package}::$func_name called on a closed handle\");
+    } else {
+        croak (\"${Package}::$func_name(): $var is not a blessed SV reference\");
     }
 
 OUTPUT
diff --git a/src/generator.ml b/src/generator.ml
index 0ffd3c7..f5e7474 100755
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -8803,9 +8803,24 @@ _create ()
 
 void
 DESTROY (g)
+      guestfs_h *g = (guestfs_h *) SvIV ((SV *) SvRV (ST(0)));
+ PPCODE:
+      /* For the 'g' argument above we do the conversion explicitly and
+       * don't rely on the typemap, because if the handle has been
+       * explicitly closed we don't want the typemap conversion to
+       * display an error.  This means we need another check for NULL
+       * here.  (RHBZ#602592)
+       */
+      if (g != NULL)
+        guestfs_close (g);
+
+void
+close (g)
       guestfs_h *g;
  PPCODE:
       guestfs_close (g);
+      /* Avoid double-close in DESTROY method. */
+      sv_setiv ((SV *) SvRV (ST(0)), PTR2IV (NULL));
 
 ";
 
@@ -9165,6 +9180,22 @@ sub new {
   return $self;
 }
 
+=item $h->close ();
+
+Explicitly close the guestfs handle.
+
+B<Note:> You should not usually call this function.  The handle will
+be closed implicitly when its reference count goes to zero (eg.
+when it goes out of scope or the program ends).  This call is
+only required in some exceptional cases, such as where the program
+may contain cached references to the handle 'somewhere' and you
+really have to have the close happen right away.  After calling
+C<close> the program must not call any method (including C<close>)
+on the handle (but the implicit call to C<DESTROY> that happens
+when the final reference is cleaned up is OK).
+
+=cut
+
 " max_proc_nr;
 
   (* Actions.  We only need to print documentation for these as
-- 
1.6.6.1