Dynamic topological sort
Keeps a topological order while edges are added one at a time, and moves only the vertices between the two ends of an edge that points backward.
Time complexity O(V+E) per edge, gograph function Graph.AddEdge.
gograph does this inside AddEdge on a graph created with gograph.Acyclic. It doesn't expose the order it keeps, so the order on this page comes from the step-by-step copy.
How it works
A build tool that adds dependencies one at a time has to know right away when a new one closes a loop. Sorting the whole graph again after every edge costs O(V+E) each time, which adds up as the graph grows. Pearce and Kelly's dynamic topological sort keeps an order instead, and when a new edge points backward in it, reorders only the vertices between the edge's two ends.
An edge that already points forward needs nothing. Neither does an edge from a vertex with no incoming edges, which can move to the front, or to a vertex with no outgoing edges, which can move to the end. Any other backward edge first searches forward from its destination among the vertices placed before its source. Reaching the source means the edge would close a loop, and AddEdge returns ErrDAGCycle without adding it.
Otherwise gograph runs two walks side by side, each allowed a number of edges that doubles every round, and uses the first to finish. The walk back from the source finds the vertices placed after the destination that reach the source. They swap places with the ones the forward search found, so each set keeps its order and every edge still points forward. The walk forward finds everything the destination reaches, and if it finishes first, all of it moves to the end of the order. Either way an edge costs little more than one search over the vertices the destination reaches.
All of this happens inside g.AddEdge on a graph created with gograph.Acyclic, and gograph.TopologySort still gives an order on demand. The order AddEdge keeps isn't exposed, so the steps here come from a copy of it, checked against the edges gograph turns away, and in the site's tests against gographtest.IsTopologicalOrder.
Build pipeline
The jobs of a CI pipeline for a web service, and how many minutes each one takes. Each edge points from a job to a job that waits for it.
A directed graph with 7 vertices and 9 edges.
A build tool meets the jobs from Deploy back to Checkout and reads their dependencies in no particular order. Add them one by one and keep a valid build order the whole time.
AddEdge accepts all 9 edges, and the order it keeps is a valid build order after each one.
Step by step
- Start with the 7 vertices and no edges, from Deploy back to Checkout. Each new vertex goes after the others, so the order starts as the order they were added in, and every edge below is added in a fixed mixed order.
- Add the edge from Checkout to Docker image. Docker image is at 2, before Checkout at 7, but nothing points to Checkout yet, so Checkout moves to the front without a search.
- Add the edge from Unit tests to Deploy. Deploy is at 2, before Unit tests at 4, but nothing points to Unit tests yet, so Unit tests moves to the front without a search.
- Add the edge from Install to Compile. Compile is at 5, before Install at 7, but nothing points to Install yet, so Install moves to the front without a search.
- Add the edge from Compile to Unit tests. Unit tests is at 2, before Compile at 6, and both ends already have edges, so it needs a search. Searching forward from Unit tests among the vertices placed before Compile finds Unit tests and Deploy and doesn't reach Compile, so there is no loop.
- Two walks run side by side: one back from Compile through the vertices placed after Unit tests, and one forward through everything Unit tests reaches. The walk back finishes first, after 1 edge: nothing placed after Unit tests reaches Compile. Compile's side takes the first of the places the two sides hold, and the side found ahead takes the rest, each in the order it had. Compile, Unit tests and Deploy get new places.
6 more steps lead to the last one:
- Done. AddEdge added 9 edges, 2 of them needed a reorder and 10 vertices moved in all. The searches visited 5 vertices in all, where sorting the whole graph after every edge would visit all 7 each time, 63 in all.
Use it in Go
g := gograph.New[string](gograph.Directed(), gograph.Acyclic())
for _, label := range labels {
g.AddVertexByLabel(label)
}
for _, d := range deps {
// AddEdge keeps a topological order and reorders only what it must.
_, err := g.AddEdge(g.GetVertexByID(d[0]), g.GetVertexByID(d[1]))
if errors.Is(err, gograph.ErrDAGCycle) {
fmt.Println(d[0], "->", d[1]) // would close a loop, turned away
}
}
Example graphs
- Build pipeline, 7 vertices and 9 edges
- Course prerequisites, 14 vertices and 18 edges
- Import cycles, 18 vertices and 30 edges
- Go module graph, 62 vertices and 116 edges
- Monorepo build, 100 vertices and 266 edges
More in Ordering
- Topological sort: Puts the vertices of a graph without cycles in an order where every edge points forward, taking vertices in the order they become ready.
- Stable topological sort: Puts the vertices of a graph without cycles in an order where every edge points forward, taking the ready vertex that comes first alphabetically.
- Topological levels: Splits a graph without cycles into levels, so that every edge goes to a later level and each level can run at the same time.
- Ready-set tracker: Hands out the tasks of a graph without cycles as soon as every task they depend on is done, so a slow task holds up only the tasks that wait for it.