[Xapian-devel] A few more question about LETOR

[Olly Betts]

On Tue, Mar 11, 2014 at 11:39:39AM +0100, Parth Gupta wrote:
> > 1.Could you explain why are these libraries included in all the
> > xapian-letor headers?
> > #include<xapian/intrusive_ptr.h>
> > #include<xapian/types.h>
> > #include<xapian/visibility.h>
> >
> > Or just provide me with the documentation of these header. I looked into
> > these header files but couldn't anything substantial.
> 
> This header connect the xapian-letor to the xapian-core.  But Olly will be
> able to throw more light on intrusive_ptr.h as he migrated the letor code
> from xapian-core/letor to what is not as xapian-letor/

We use the PIMPL idiom for many of the Xapian API classes (though not
all - e.g. MSetIterator isn't, as it's just a thin wrapper around
an MSet object and an index; and classes which need to be
user-subclassable don't use it, as it doesn't really work for those).

There's a reasonably good explanation of this technique on wikipedia:

http://en.wikipedia.org/wiki/Opaque_pointer#C.2B.2B

Our implementation of it uses a referenced counted pointer to the
implementation, and intrusive_ptr<> is the implementation of that
reference counted pointer.  It's actually a lightly patched version of
Boost's intrusive_ptr<> implementation.

We used to have our own implementation (RefCntPtr<> in base.h, which
predates Boost having this, but it seemed more sensible to use a version
which somebody else maintains for us.  It's not ideal having a patched
version, but the current situation is certainly no worse than with
base.h.

As for the other two headers:

* xapian/types.h has the typedefs for various Xapian types (e.g.
  Xapian::termcount, Xapian::docid).  Letor should use these rather than
  standard C types like int, long, unsigned, unsigned long, etc, to ease
  extending Xapian to handle more the 4 billion documents or terms.  I
  think currently this isn't done in some places in Letor - those should
  all be fixed.

* xapian/visibility.h supports symbol visibility annotations for
  compilers and platforms which support it (which is at least all ELF
  platforms with GCC 4.x).  The key thing to know is that this speeds up
  loading the library, but http://gcc.gnu.org/wiki/Visibility covers the
  details of how this works.

Cheers,
    Olly