Re: [PATCH v3] lib: Simplify close and codify aborting atomic section

diff --git a/95/2d6d668b91dfe5f90592ea69a3a9e7d8c76d65 b/95/2d6d668b91dfe5f90592ea69a3a9e7d8c76d65
new file mode 100644 (file)
index 0000000..fb8691b
--- /dev/null
+++ b/95/2d6d668b91dfe5f90592ea69a3a9e7d8c76d65
@@ -0,0 +1,100 @@
+Return-Path: <aclements@csail.mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+       by olra.theworths.org (Postfix) with ESMTP id 2CA8F431FBC\r
+       for <notmuch@notmuchmail.org>; Thu,  2 Oct 2014 12:18:54 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -2.3\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5\r
+       tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+       by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+       with ESMTP id Mw4ox0DrvKFq for <notmuch@notmuchmail.org>;\r
+       Thu,  2 Oct 2014 12:18:48 -0700 (PDT)\r
+Received: from outgoing.csail.mit.edu (outgoing.csail.mit.edu [128.30.2.149])\r
+       by olra.theworths.org (Postfix) with ESMTP id 00ECA431FB6\r
+       for <notmuch@notmuchmail.org>; Thu,  2 Oct 2014 12:18:47 -0700 (PDT)\r
+Received: from [104.131.20.129] (helo=awakeningjr)\r
+       by outgoing.csail.mit.edu with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16)\r
+       (Exim 4.72) (envelope-from <aclements@csail.mit.edu>)\r
+       id 1XZltk-0007rB-QU; Thu, 02 Oct 2014 15:18:44 -0400\r
+Received: from amthrax by awakeningjr with local (Exim 4.84)\r
+       (envelope-from <aclements@csail.mit.edu>)\r
+       id 1XZltk-0005Xo-8v; Thu, 02 Oct 2014 15:18:44 -0400\r
+From: Austin Clements <aclements@csail.mit.edu>\r
+To: "W. Trevor King" <wking@tremily.us>\r
+Subject: Re: [PATCH v3] lib: Simplify close and codify aborting atomic section\r
+In-Reply-To: <20140924213910.GF20130@odin.tremily.us>\r
+References: <20140924212839.GE20130@odin.tremily.us>\r
+       <1411594370-9794-1-git-send-email-aclements@csail.mit.edu>\r
+       <20140924213910.GF20130@odin.tremily.us>\r
+User-Agent: Notmuch/0.18.1+86~gef5e66a (http://notmuchmail.org) Emacs/24.3.1\r
+       (x86_64-pc-linux-gnu)\r
+Date: Thu, 02 Oct 2014 15:18:44 -0400\r
+Message-ID: <87mw9ee0vf.fsf@csail.mit.edu>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+       <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Thu, 02 Oct 2014 19:18:54 -0000\r
+\r
+On Wed, 24 Sep 2014, "W. Trevor King" <wking@tremily.us> wrote:\r
+> On Wed, Sep 24, 2014 at 05:32:50PM -0400, Austin Clements wrote:\r
+>> + * If the caller is currently in an atomic section (there was a\r
+>> + * notmuch_database_begin_atomic without a matching\r
+>> + * notmuch_database_end_atomic), this will abort the atomic section,\r
+>> + * discarding any modifications made in the atomic section.  All\r
+>> + * changes up to this will be committed.\r
+>\r
+> I still think Xapian's wording is more readable [1]:\r
+>\r
+>   For a WritableDatabase, if a transaction is active it will be\r
+>   aborted, while if no transaction is active commit() will be\r
+>   implicitly called.\r
+>\r
+> How about:\r
+>\r
+>   For a writable database, if a transaction is active (there was a\r
+>   notmuch_database_begin_atomic without a matching\r
+>   notmuch_database_end_atomic) it will be aborted, while if no\r
+>   transaction is active any pending changes will be committed.\r
+\r
+What is a "pending change" from the perspective of the notmuch API?\r
+This is tricky because basically nothing in the library talks about\r
+durability (partly because the notmuch API provides almost no control\r
+over it).  Likewise, the API doesn't expose the notion of a transaction\r
+(since that generally implies ACID), but only atomic sections.\r
+\r
+I actually find the Xapian wording rather confusing.  Neither Xapian's\r
+documentation nor your suggested comment say what happens when there is\r
+*both* an outstanding transaction and pending changes.  In fact, teasing\r
+this out made me realize that Xapian might in fact discard committed\r
+(but unflushed) changes if you close the database with an outstanding\r
+transaction.  But we definitely do want to flush these transactions\r
+(especially since *all* of our atomic sections are "unflushed\r
+transactions").  In v4 I've added some code to make sure this happens,\r
+but because of the vagueness of the documentation I have no idea if it's\r
+necessary.\r
+\r
+> Cheers,\r
+> Trevor\r
+>\r
+> [1]: http://xapian.org/docs/apidoc/html/classXapian_1_1Database.html#a59f5f8b137723dcaaabdbdccbc0cf1eb\r
+>\r
+> -- \r
+> This email may be signed or encrypted with GnuPG (http://www.gnupg.org).\r
+> For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy\r