From 9e29216cef8b51ea26b04ebc74c18f53a7ee007a Mon Sep 17 00:00:00 2001 From: Ben Vandervalk Date: Fri, 9 Nov 2018 10:23:25 -0800 Subject: [PATCH] ExtendPath.h: add documentation to tricky `trueBranch` method --- Graph/ExtendPath.h | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/Graph/ExtendPath.h b/Graph/ExtendPath.h index 3de04b5c2..540f18b74 100644 --- a/Graph/ExtendPath.h +++ b/Graph/ExtendPath.h @@ -160,11 +160,14 @@ static inline bool lookAhead( } /** - * Return true if the given edge represents the start of a "true branch". - * Roughly speaking, a path is a true branch if it has length >= trim - * or terminates in a branching node, where a branching node is (recursively) - * defined to be a node with either >= 2 incoming true branches or >= outgoing - * true branches. + * Return true if the given edge represents the beginning of a "true branch". + * + * A path is a true branch if it has length >= `trim` or terminates in a + * branching node, where a branching node is (recursively) defined to be + * a node with either >= 2 incoming true branches or >= 2 outgoing true branches. + * + * This method is similar to `lookAhead`, but it additionally changes traversal + * direction when a dead-end is encountered. */ template static inline bool trueBranch( @@ -195,6 +198,12 @@ static inline bool trueBranch( if (trueBranch(*oei, depth+1, FORWARD, g, trim, fpTrim, visited)) return true; } + /* + * Note: The test for depth/lookAhead >= fpTrim before changing + * traversal direction is needed to deal with an X-shaped + * graph pattern that is frequently created by Bloom false positives. + * See the test for `trueBranch` in `ExtendPathTest.h` for an example. + */ if (depth >= fpTrim || lookAhead(v, FORWARD, fpTrim, g)) { for (boost::tie(iei, iei_end) = in_edges(v, g); iei != iei_end; ++iei) { @@ -211,6 +220,12 @@ static inline bool trueBranch( if (trueBranch(*iei, depth+1, REVERSE, g, trim, fpTrim, visited)) return true; } + /* + * Note: The test for depth/lookAhead >= fpTrim before changing + * traversal direction is needed to deal with an X-shaped + * graph pattern that is frequently created by Bloom false positives. + * See the test for `trueBranch` in `ExtendPathTest.h` for an example. + */ if (depth >= fpTrim || lookAhead(v, REVERSE, fpTrim, g)) { for (boost::tie(oei, oei_end) = out_edges(v, g); oei != oei_end; ++oei) {