org.graalvm.graphio.GraphStructure Maven / Gradle / Ivy
/*
* Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.graalvm.graphio;
import java.util.Collection;
import java.util.Map;
/**
* Interface that defines structure of a compiler graph. The structure of a graph is composed from
* nodes with properties, the classes of individual nodes, and ports associated with each node that
* may contain edges to other nodes. The structure of a graph is assumed to be immutable for the
* time of {@link GraphOutput operations} on it.
*
* @param the type of the (root node of a) graph
* @param the type of nodes
* @param the type of node classes
* @param the type of node ports
*/
public interface GraphStructure {
/**
* Casts {@code obj} to graph, if possible. If the given object obj can be seen as
* a graph or sub-graph of a graph, then return the properly typed instance. Otherwise return
* null
*
* @param currentGraph the currently processed graph
* @param obj an object to check and view as a graph
* @return appropriate graph object or null if the object doesn't represent a graph
*/
G graph(G currentGraph, Object obj);
/**
* Nodes of a graph. Each graph is composed from a fixed set of nodes. This method returns an
* iterable which provides access to all of them - the number of nodes provided by the iterable
* must match the number returned by {@link #nodesCount(java.lang.Object)} method.
*
* @see #nodesCount(java.lang.Object)
* @param graph the graph to query for nodes
* @return iterable with all the graph's nodes
*/
Iterable nodes(G graph);
/**
* Number of nodes in a graph. The number must match the content returned by
* {@link #nodes(java.lang.Object)} method.
*
* @param graph the graph to query
* @return the number of nodes that will be returned by {@link #nodes(java.lang.Object)}
*/
int nodesCount(G graph);
/**
* Id of {@code node}. Each node in the graph is uniquely identified by an integer value. If two
* nodes have the same id, then they shall be == to each other.
*
* @param node the node to query for an id
* @return the id of the node
*/
int nodeId(N node);
/**
* Checks if there is a predecessor for a node.
*
* @param node the node to check
* @return true if it has a predecessor, false otherwise
*/
boolean nodeHasPredecessor(N node);
/**
* Collects node properties. Each node can be associated with additional properties identified
* by their name. This method shall copy them into the provided map.
*
* @param graph the current graph
* @param node the node to collect properties for
* @param properties the map to put the properties to
*/
void nodeProperties(G graph, N node, Map properties);
/**
* Finds a node for {@code obj}, if possible. If the given object obj can be seen
* as an instance of node return the properly typed instance of the node class. Otherwise return
* null.
*
* @param obj an object to find node for
* @return appropriate graph object or null if the object doesn't represent a node
*/
N node(Object obj);
/**
* Finds a node class for {@code obj}, if possible. If the given object obj can be
* seen as an instance of node class return the properly typed instance of the node class.
* Otherwise return null.
*
* @param obj an object to find node class for
* @return appropriate graph object or null if the object doesn't represent a node
* class
*/
C nodeClass(Object obj);
/**
* Finds a node class for {@code node}.
*
* @param node an instance of node in this graph
* @return the node's node class, never null
*/
C classForNode(N node);
/**
* The template used to build the name of nodes of this class. The template may use references
* to inputs ({i#inputName}) and its properties ({p#propertyName}).
*
* @param nodeClass the node class to find name template for
* @return the string representing the template
*/
String nameTemplate(C nodeClass);
/**
* Java class for a node class.
*
* @param nodeClass the node class
* @return the {@link Class} or other type representation of the node class
*/
Object nodeClassType(C nodeClass);
/**
* Input ports of a node class. Each node class has a fixed set of ports where individual edges
* can attach to.
*
* @param nodeClass the node class
* @return input ports for the node class
*/
P portInputs(C nodeClass);
/**
* Output ports of a node class. Each node class has a fixed set of ports from where individual
* edges can point to other nodes.
*
* @param nodeClass the node class
* @return output ports for the node class
*/
P portOutputs(C nodeClass);
/**
* The number of edges in a port. The protocol will then call methods
* {@link #edgeDirect(java.lang.Object, int)}, {@link #edgeName(java.lang.Object, int)},
* {@link #edgeType(java.lang.Object, int)} and
* {@link #edgeNodes(java.lang.Object, java.lang.Object, java.lang.Object, int)} for indexes
* from 0 to portSize - 1
*
* @param port the port
* @return number of edges in this port
*/
int portSize(P port);
/**
* Checks whether an edge is direct. Direct edge shall have exactly one
* {@linkplain #edgeNodes(java.lang.Object, java.lang.Object, java.lang.Object, int) node} - it
* is an error to return more than one for such an edge from the
* {@linkplain #edgeNodes(java.lang.Object, java.lang.Object, java.lang.Object, int) method}.
*
* @param port the port
* @param index index from 0 to {@link #portSize(java.lang.Object)} minus
* 1
* @return true if only one node can be returned from
* {@link #edgeNodes(java.lang.Object, java.lang.Object, java.lang.Object, int)} method
*/
boolean edgeDirect(P port, int index);
/**
* The name of an edge.
*
* @param port the port
* @param index index from 0 to {@link #portSize(java.lang.Object)} minus
* 1
* @return the name of the edge
*/
String edgeName(P port, int index);
/**
* Type of an edge. The type must be a graph
* enum
- e.g. either real instance of {@link Enum} subclass, or something that the
* {@link GraphOutput.Builder} can recognize as
* enum
.
*
* @param port
* @param index index from 0 to {@link #portSize(java.lang.Object)} minus
* 1
* @return any {@link Enum} representing type of the edge
*/
Object edgeType(P port, int index);
/**
* Nodes where the edges for a port lead to/from. This method is called for both
* {@link #edgeDirect(java.lang.Object, int) direct/non-direct edges}. In case of a direct edge
* the returned collection must have exactly one element.
*
* @param graph the graph
* @param node the node in the graph
* @param port port of the node class
* @param index index from 0 to {@link #portSize(java.lang.Object)} minus
* 1
* @return null if there are no edges associated with given port or collection of
* nodes where to/from the edges lead to
*/
Collection edgeNodes(G graph, N node, P port, int index);
}