API reference — graph view

The generic graph description, stride-aware edge derivation, the layered layout and the ASCII / Mermaid / DOT renderers, plus the adapters from eagle’s native graphs. Header-only and CUDA-free; the guide is Seeing a graph from C++: eagle/graph.

Namespace eagle::graph

namespace graph

Typedefs

using gidx = std::int64_t

Signed index of nodes, frames and edges (-1 = none).

Enums

enum class EdgeKind

The hazard an edge carries: read-after-write, write-after-read or write-after-write. Only RAW carries data (adjoint) flow.

Values:

enumerator RAW

enumerator WAR

enumerator WAW

Functions

inline Description describe(const cpu::Graph &g)

The host graph: one node per native node, an edge per dependency.

inline Description describe(const cuda::Graph &g)

The CUDA graph: one node per native node, an edge per dependency.

inline Description describe(const compose::GraphComposer &c)

A composer: one node per member (its name, else member<i>). Under mode="sequenced" members replay in registration order, so they form a chain; the flat modes (enabled, rebuild) run members as siblings and carry no edges.

inline Description describe(const conditional::ConditionalGroup&, Description body)

A conditional group around body (its description): every top-level node of body moves into one new "if" frame.

inline const char *kindName(EdgeKind k)

"RAW", "WAR" or "WAW".

inline const char *kindMeaning(EdgeKind k)

What a hazard means, in plain words: RAW “data flows”, WAR “must wait

to overwrite”, WAW “same output”.

inline EdgeKind parseEdgeKind(const std::string &s)

The inverse of kindName.

Throws:

std::invalid_argument – for any other text.

inline std::vector<Edge> deriveEdges(const std::vector<PlaneRef> &refs, const std::vector<SiblingGroup> &groups = {})

Every hazard edge between nodes, in add order (ascending source, then destination), siblings of one group excluded (their overlap is a conflict, see siblingConflicts). A hazard on the same plane name between the same two nodes collapses to one edge per kind.

inline std::vector<Conflict> siblingConflicts(const std::vector<PlaneRef> &refs, const std::vector<SiblingGroup> &groups)

Overlaps between siblings of one group, at least one side writing: every one is a race, not an ordering.

inline std::vector<Conflict> siblingConflicts(const std::vector<PlaneRef> &refs, const std::vector<std::vector<gidx>> &groups)

The flat form: each inner list is a set of nodes that each sit in a branch of their own.

inline Layout layout(const Description &d, int sweeps = 4)

Lay out d. sweeps is the number of down-and-up barycenter rounds; the ordering with the fewest crossings seen (the initial id order included) wins, the earliest on a tie.

Throws:

std::invalid_argument – if d fails validate().

inline std::string ascii(const Description &d, const Layout &lay, bool unicode = true, std::size_t maxLabel = 24)

The box block diagram: one box per node placed by the layout’s layer (row) and order (column), edges routed between the boxes with the plane names under the source (:WAR / :WAW appended when the hazard is not a read-after-write), an edge that skips layers carried down as a vertical line through the layers in between, a conditional as a frame around its nodes (its label in the top border), an opaque node with a dashed border, and a stage <k> <schedule> tag in the left gutter. unicode = false draws with + - | only. A label longer than maxLabel cells is cut with an ellipsis. Deterministic: the same Description and Layout always give the same text.

A frame is drawn as the bounding box of its nodes; a node of another frame that falls inside that box is not moved out of it.

inline std::string ascii(const Description &d)

The box diagram with the default layout.

inline std::string mermaid(const Description &d)

Mermaid flowchart TD: frames as subgraphs, opaque nodes in the opaque class (dashed), edge arrow by kind (RAW -->, WAR -.->, WAW ==>) labelled with the plane.

inline std::string dot(const Description &d)

Graphviz DOT: frames as clusters, an opaque node dashed, edge style by kind (RAW solid, WAR dashed, WAW bold) labelled with the plane.

Variables

std::int64_t kOverlapMaxWork = 100000

Work cap of the exact overlap search (search steps).

struct Conflict

#include <Edges.h>

Two sibling nodes touching overlapping memory, at least one of them writing. kind is the hazard from a (earlier) to b.

struct Description

#include <Description.h>

Nodes, edges and frames. Ids equal positions.

Public Functions

inline void validate() const

Check the description is well formed.

Throws:

std::invalid_argument – naming the first defect: an id that is not its position, an edge or node frame pointing nowhere, a self edge, a frame cycle, or an edge cycle.

struct Edge

#include <Description.h>

src must finish before dst starts.

struct Frame

#include <Description.h>

A region wrapped around nodes: a skippable ("if"), a loop ("while") or a plain stage band ("stage"). parent is the enclosing frame’s id, -1 at top level.

Public Functions

inline const std::string &text() const

The text drawn on the frame: its label, else its kind.

struct Layout

#include <Layout.h>

layer[v] and order[v] (position inside the layer) per node; xy[v] = {order - (width - 1) / 2, layer}, y growing downwards.

struct Node

#include <Description.h>

One executable node. stage is the schedule it runs under ("work_share", "branch_tasks", "capture") or empty before a build; frame the id of the frame it sits in or -1; opaque marks a node whose planes were declared by the caller.

struct PlaneRef

#include <Edges.h>

One plane a node touches. access: 0 read, 1 write, 2 in place (read and write). strides are in bytes and may be negative.

struct SiblingGroup

#include <Edges.h>

The branches of one fork/join group: branches[b] lists the nodes of branch b (run in order inside the branch). Nodes of different branches are siblings; they may run concurrently.

The busy guard

eagle::util::BusyGuard and eagle::util::Busy live in eagle/util/Busy.h and are listed with the rest of eagle::util on API reference — util.