Xapian concurrency

[Olly Betts]

On Mon, Apr 29, 2024 at 07:20:44AM +0300, Dirk-Jan C. Binnema wrote:
> Hadn't noticed that Xapian::Document and others gained move-ctors /
> assignment operators, and they have been there for a while! Seems
> the docs don't mention that yet[1].

Ah yes, you need to define XAPIAN_MOVE_SEMANTICS before including
<xapian.h> to get them - the 1.4.6 NEWS entry about this says:

  API classes now support C++11 move semantics when using a compiler which
  we are confident supports them (currently compilers which define
  __cplusplus >= 201103 plus a special check for MSVC 2015 or later).
  C++11 move semantics provide a clean and efficient way for threaded code to
  hand-off Xapian objects to worker threads, but in this case it's very
  unhelpful for availability of these semantics to vary by compiler as it    
  quietly leads to a build with non-threadsafe behaviour.  To address this,
  user code can #define XAPIAN_MOVE_SEMANTICS before #include <xapian.h> to
  force this on, and will then get a compilation failure if the compiler lacks
  suitable support.

At the point where 1.4.6 was released, it was common for compilers to
support C++11 but require a command line option to enable that support.
That's rather less of a concern in 2024 than it was in 2018 as it seems
all the actively maintained C++ compilers default to C++11 or newer now.
I think it's probably unwise to drop the check at this point though as
it affects older versions of compilers we still aim to support in 1.4.x
(the next stable release series will require at least C++11 for code
including the Xapian API headers so it'll be gone there).

Because these move methods are gated by `#ifdef XAPIAN_MOVE_SEMANTICS`
doxygen doesn't see them so they aren't visible in the API
documentation.

I think we can define XAPIAN_MOVE_SEMANTICS for doxygen and add a note
to the doxygen comments that you need to define XAPIAN_MOVE_SEMANTICS
to get them.

Cheers,
    Olly