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

[Austin Clements]

On Wed, 24 Sep 2014, "W. Trevor King" <wking at tremily.us> wrote:
> On Wed, Sep 24, 2014 at 05:32:50PM -0400, Austin Clements wrote:
>> + * If the caller is currently in an atomic section (there was a
>> + * notmuch_database_begin_atomic without a matching
>> + * notmuch_database_end_atomic), this will abort the atomic section,
>> + * discarding any modifications made in the atomic section.  All
>> + * changes up to this will be committed.
>
> I still think Xapian's wording is more readable [1]:
>
>   For a WritableDatabase, if a transaction is active it will be
>   aborted, while if no transaction is active commit() will be
>   implicitly called.
>
> How about:
>
>   For a writable database, if a transaction is active (there was a
>   notmuch_database_begin_atomic without a matching
>   notmuch_database_end_atomic) it will be aborted, while if no
>   transaction is active any pending changes will be committed.

What is a "pending change" from the perspective of the notmuch API?
This is tricky because basically nothing in the library talks about
durability (partly because the notmuch API provides almost no control
over it).  Likewise, the API doesn't expose the notion of a transaction
(since that generally implies ACID), but only atomic sections.

I actually find the Xapian wording rather confusing.  Neither Xapian's
documentation nor your suggested comment say what happens when there is
*both* an outstanding transaction and pending changes.  In fact, teasing
this out made me realize that Xapian might in fact discard committed
(but unflushed) changes if you close the database with an outstanding
transaction.  But we definitely do want to flush these transactions
(especially since *all* of our atomic sections are "unflushed
transactions").  In v4 I've added some code to make sure this happens,
but because of the vagueness of the documentation I have no idea if it's
necessary.

> Cheers,
> Trevor
>
> [1]: http://xapian.org/docs/apidoc/html/classXapian_1_1Database.html#a59f5f8b137723dcaaabdbdccbc0cf1eb
>
> -- 
> This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
> For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy