Package com.apple.foundationdb.record.query.plan.temp

Class TopologicalSort

java.lang.Object

com.apple.foundationdb.record.query.plan.temp.TopologicalSort

@API(EXPERIMENTAL)
public class TopologicalSort
extends Object

Utility class to provide helpers related to topological sorts. The main purpose on this class is to provide a specific iterable that can efficiently traverse all possible permutations of the input set that do not violate the given dependency constraints. The iterable EnumeratingIterable adheres to the following requirements:

1. it does not violate the given constraints
2. it produces all possible orderings under the given constraints
3. it reacts appropriately to give circular dependency constraints between elements (i.e., no infinite loops)
4. it iterates all orderings on the fly. That is, it stores only the position of the iteration and does not (pre)create the orderings in memory.

EnumeratingIterable subclasses Iterable in order to provide an additional feature that allows for skipping. Assume we have a set

 
 { a, b, c, d } with constraints { b -> c, b -> d } (c depends on b, d depends on b)
 
 

Possible orderings are

 
 (a, b, c, d)
 (a, b, d, c)
 (b, a, c, d)
 (b, a, d, c)
 (b, c, a, d)
 (b, c, d, a)
 (b, d, a, c)
 (b, d, c, a)
 
 

Frequently we test for a certain property or perform a particular operation given one possible ordering but it is clear that it is not necessary to consider more such orderings that share a common prefix. In the example, it may be beneficial to skip the rest of the (b, a, ...) orderings after the first one was returned ((b, a, c, d). In this case we would like to instruct the iterator to skip all such orderings and continue iteration at (b, c, a, d). Similarly, we want to skip all orderings starting with (b, ...) once we encountered the first such ordering. This the iterators created by the provided EnumeratingIterable of type EnumeratingIterator provide a method EnumeratingIterator.skip(int) to allow skipping to a given prefix.

Method Summary

Modifier and Type	Method	Description
static <T> Optional<List<T>>	anyTopologicalOrderPermutation(Set<T> set, com.google.common.collect.ImmutableSetMultimap<T,T> dependsOnMap)	Create a correct topological ordering based on a set and a function describing the depends-on relationships between items in the given set.
static <T> Optional<List<T>>	anyTopologicalOrderPermutation(Set<T> set, Function<T,Set<T>> dependsOnFn)	Create a correct topological ordering based on a set and a function describing the depends-on relationships between items in the given set.
static <T> EnumeratingIterable<T>	permutations(Set<T> set)	Create an EnumeratingIterable based on a set.
static <T> EnumeratingIterable<T>	topologicalOrderPermutations(Set<T> set, com.google.common.collect.ImmutableSetMultimap<T,T> dependsOnMap)	Create an EnumeratingIterable based on a set and a function describing the depends-on relationships between items in the given set.
static <T> EnumeratingIterable<T>	topologicalOrderPermutations(Set<T> set, Function<T,Set<T>> dependsOnFn)	Create an EnumeratingIterable based on a set and a function describing the depends-on relationships between items in the given set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

permutations

public static <T> EnumeratingIterable<T> permutations(@Nonnull
                                                      Set<T> set)

Create an EnumeratingIterable based on a set.

Type Parameters:

T - type

Parameters:

set - the set to create the iterable over

Returns:

a new EnumeratingIterable that enumerates all permutations of the given set

topologicalOrderPermutations

public static <T> EnumeratingIterable<T> topologicalOrderPermutations(@Nonnull
                                                                      Set<T> set,
                                                                      @Nonnull
                                                                      Function<T,Set<T>> dependsOnFn)

Create an EnumeratingIterable based on a set and a function describing the depends-on relationships between items in the given set.

Type Parameters:

T - type

Parameters:

set - the set to create the iterable over

dependsOnFn - a function from T to Set<T> that can be called during the lifecycle of all iterators multiple times repeatedly or not at all for any given element in set. This method is expected to return instantly and must be stable. Note it is allowed for the set the given function returns to contain elements of type T that are not in set. These items are ignored by the underlying algorithm (that is, they are satisfied by every ordering).

Returns:

a new EnumeratingIterable that obeys the constraints as expressed in dependsOnFn in a sense that the iterators created by this iterator will not return orderings that violate the given depends-on constraints

topologicalOrderPermutations

public static <T> EnumeratingIterable<T> topologicalOrderPermutations(@Nonnull
                                                                      Set<T> set,
                                                                      @Nonnull
                                                                      com.google.common.collect.ImmutableSetMultimap<T,T> dependsOnMap)

Create an EnumeratingIterable based on a set and a function describing the depends-on relationships between items in the given set.

Type Parameters:

T - type

Parameters:

set - the set to create the iterable over

dependsOnMap - a set-based multimap from T to T describing the dependencies between entities. The key entity of the map depends on each entity in the set of values for that key.

Returns:

a new EnumeratingIterable that obeys the constraints as expressed in dependsOnFn in a sense that the iterators created by this iterator will not return orderings that violate the given depends-on constraints

anyTopologicalOrderPermutation

public static <T> Optional<List<T>> anyTopologicalOrderPermutation(@Nonnull
                                                                   Set<T> set,
                                                                   @Nonnull
                                                                   Function<T,Set<T>> dependsOnFn)

Create a correct topological ordering based on a set and a function describing the depends-on relationships between items in the given set.

Type Parameters:

T - type

Parameters:

set - the set to create the iterable over

dependsOnFn - a function from T to Set<T> that can be called during the lifecycle of all iterators multiple times repeatedly or not at all for any given element in set. This method is expected to return instantly and must be stable. Note it is allowed for the set the given function returns to contain elements of type T that are not in set. These items are ignored by the underlying algorithm (that is, they are satisfied by every ordering).

Returns:

a permutation of the set that is topologically correctly ordered with respect to dependsOnFn

anyTopologicalOrderPermutation

public static <T> Optional<List<T>> anyTopologicalOrderPermutation(@Nonnull
                                                                   Set<T> set,
                                                                   @Nonnull
                                                                   com.google.common.collect.ImmutableSetMultimap<T,T> dependsOnMap)

Create a correct topological ordering based on a set and a function describing the depends-on relationships between items in the given set.

Type Parameters:

T - type

Parameters:

set - the set to create the iterable over

dependsOnMap - a set-based multimap from T to T describing the dependencies between entities. The key entity of the map depends on each entity in the set of values for that key.

Returns:

a permutation of the set that is topologically correctly ordered with respect to dependsOnFn