rust/README.rst

setdiscovery: make progress on most connected groups each roundtrip

Consider history like this:

  o
  | o
  | |
  | o
  | |
  | o
  |/
  o
  | o
  | |
  | o
  | |
  | o
  |/
  o
  | o
  | |
  | o
  | |
  | o
  |/
  o
  ~

Assume the left mainline is available in the remote repo and the other
commits are only in the local repo. Also imagine that instead of 3
local branches with 3 commits on each, there are 1000 branches (the
number of commits on each doesn't matter much here). In such a
scenario, the current setdiscovery code will pick a sample size of 200
among these branches and ask the remote which of them it has. However,
the discovery for each such branch is completely independent of the
discovery for the others -- knowing whether the remote has a commit in
one branch doesn't give us any information about the other
branches. The discovery will therefore take at least 5 roundtrips
(maybe more depending on which commit in each linear chain was
sampled). Since the discovery for each branch is independent, there is
no reason to let one branch wait for another, so this patch makes it
so we sample at least as many commits as there are branches. It may
still happen (it's very likely, even) that we get multiple samples
from one branch and none from another, but that will even out over a
few rounds and I think this is still a big improvement.

Because of http header size limits, we still use the old behavior
unless experimental.httppostargs=true.

I've timed this by running `hg debugdiscovery mozilla-unified --debug` in the
mozilla-try repo. Both repos were local. Before this patch, last part
of the output was:


  2249 total queries in 5276.4859s
  elapsed time:  5276.652634 seconds
  heads summary:
    total common heads:         13
      also local heads:          4
      also remote heads:         8
      both:                      4
    local heads:             28317
      common:                    4
      missing:               28313
    remote heads:               12
      common:                    8
      unknown:                   4
  local changesets:        2014901
    common:                 530373
    missing:               1484528
  common heads: 1dad417c28ad 4a108e94d3e2 4d7ef530fffb 5350524bb654 777e60ca8853 7d97fafba271 9cd2ab4d0029 a55ce37217da d38398e5144e dcc6d7a0dc00 e09297892ada e24ec6070d7b fd559328eaf3


After this patch, the output was (including all the samples, since
there were so few now):

  taking initial sample
  query 2; still undecided: 1599476, sample size is: 108195
  sampling from both directions
  query 3; still undecided: 810922, sample size is: 194158
  sampling from both directions
  query 4; still undecided: 325882, sample size is: 137302
  sampling from both directions
  query 5; still undecided: 111459, sample size is: 74586
  sampling from both directions
  query 6; still undecided: 26805, sample size is: 23960
  sampling from both directions
  query 7; still undecided: 2549, sample size is: 2528
  sampling from both directions
  query 8; still undecided: 21, sample size is: 21
  8 total queries in 24.5064s
  elapsed time:  24.670051 seconds
  heads summary:
    total common heads:         13
      also local heads:          4
      also remote heads:         8
      both:                      4
    local heads:             28317
      common:                    4
      missing:               28313
    remote heads:               12
      common:                    8
      unknown:                   4
  local changesets:        2014901
    common:                 530373
    missing:               1484528
  common heads: 1dad417c28ad 4a108e94d3e2 4d7ef530fffb 5350524bb654 777e60ca8853 7d97fafba271 9cd2ab4d0029 a55ce37217da d38398e5144e dcc6d7a0dc00 e09297892ada e24ec6070d7b fd559328eaf3

Differential Revision: https://phab.mercurial-scm.org/D2647

===================
Mercurial Rust Code
===================

This directory contains various Rust code for the Mercurial project.

The top-level ``Cargo.toml`` file defines a workspace containing
all primary Mercurial crates.

Building
========

To build the Rust components::

   $ cargo build

If you prefer a non-debug / release configuration::

   $ cargo build --release

Features
--------

The following Cargo features are available:

localdev (default)
   Produce files that work with an in-source-tree build.

   In this mode, the build finds and uses a ``python2.7`` binary from
   ``PATH``. The ``hg`` binary assumes it runs from ``rust/target/<target>hg``
   and it finds Mercurial files at ``dirname($0)/../../../``.

Build Mechanism
---------------

The produced ``hg`` binary is *bound* to a CPython installation. The
binary links against and loads a CPython library that is discovered
at build time (by a ``build.rs`` Cargo build script). The Python
standard library defined by this CPython installation is also used.

Finding the appropriate CPython installation to use is done by
the ``python27-sys`` crate's ``build.rs``. Its search order is::

1. ``PYTHON_SYS_EXECUTABLE`` environment variable.
2. ``python`` executable on ``PATH``
3. ``python2`` executable on ``PATH``
4. ``python2.7`` executable on ``PATH``

Additional verification of the found Python will be performed by our
``build.rs`` to ensure it meets Mercurial's requirements.

Details about the build-time configured Python are built into the
produced ``hg`` binary. This means that a built ``hg`` binary is only
suitable for a specific, well-defined role. These roles are controlled
by Cargo features (see above).

Running
=======

The ``hgcli`` crate produces an ``hg`` binary. You can run this binary
via ``cargo run``::

   $ cargo run --manifest-path hgcli/Cargo.toml

Or directly::

   $ target/debug/hg
   $ target/release/hg

You can also run the test harness with this binary::

   $ ./run-tests.py --with-hg ../rust/target/debug/hg

.. note::

   Integration with the test harness is still preliminary. Remember to
   ``cargo build`` after changes because the test harness doesn't yet
   automatically build Rust code.