mte/unikernel/duniverse/dune_/vendor/incremental-cycles

README for incremental_cycles library

This library is vendored from https://gitlab.inria.fr/agueneau/incremental-cycles

Details on the vendoring process

The vendoring process is a bit involved due to the way the library is specified upstream. In particular, it assumes a graph interface Raw_graph that we have to copy by hand in Dune [see src/dag/dag.ml], and in particular we have to be careful about not altering the complexity guarantees.

Complexity guarantees

The complexity and correctness of the implementation of incremental_cycles has been mechanically-verified using the Coq theorem prover. Note however, that for the main theorem to hold there are a few requirements that cannot be captured by ML-level interfaces; more concretely:

• the current specification for the algorithm requires the get_outgoing function provided by the client to return a list of all successors, and do so in constant time. This is quite demanding, as basically requires the client to already have the list at hand.

• the main theorem for Dag.add does require that the vertex is not already in the graph; otherwise the theorem doesn't apply. Thus, clients must ensure that no duplicate edge is added to the graph.

Dune-specific modifications

Dune uses incremental_cycles in a way that the no-duplicate-egdes requirement is not satisfied by construction; thus, before a call to Dag.add edge membership on the graph must be checked.

This is a common operation and thus should be done efficiently, thus Dune performs the following modifications to dag.ml:

• we add a set of children nodes in addition to the current list
• we modify raw_add_edge so it updates this set, and is_child so it uses the efficient membership set

The rationale for adding a duplicate children field is to actually preserve the order the edges were added, this could be important in other parts of the algo, see comment on is_child use at memo.ml.

For more details see discussion at https://github.com/ocaml/dune/pull/2959