001 /*
002 Galois, a framework to exploit amorphous data-parallelism in irregular
003 programs.
004
005 Copyright (C) 2010, The University of Texas at Austin. All rights reserved.
006 UNIVERSITY EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES CONCERNING THIS SOFTWARE
007 AND DOCUMENTATION, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR ANY
008 PARTICULAR PURPOSE, NON-INFRINGEMENT AND WARRANTIES OF PERFORMANCE, AND ANY
009 WARRANTY THAT MIGHT OTHERWISE ARISE FROM COURSE OF DEALING OR USAGE OF TRADE.
010 NO WARRANTY IS EITHER EXPRESS OR IMPLIED WITH RESPECT TO THE USE OF THE
011 SOFTWARE OR DOCUMENTATION. Under no circumstances shall University be liable
012 for incidental, special, indirect, direct or consequential damages or loss of
013 profits, interruption of business, or related expenses which may arise from use
014 of Software or Documentation, including but not limited to those resulting from
015 defects in Software and/or Documentation, or loss or inaccuracy of data of any
016 kind.
017
018 File: LongGraph.java
019
020 */
021
022 package galois.objects.graph;
023
024 import galois.objects.GObject;
025
026 /**
027 * Interface used to represent graphs whose edges contain long data. <br/>
028 * Edges can be created <b>only</b> by invoking {@link ObjectGraph#addEdge}: invocations of
029 * {@link Graph#addNeighbor(GNode, GNode)} will result in a exception, because no edge data has been specified.
030 *
031 * @param <N> the type of the object stored in each node
032 */
033 public interface LongGraph<N extends GObject> extends Graph<N> {
034 /**
035 * Adds an edge to the graph containing the specified data.
036 *
037 * <p>
038 * All the Galois runtime actions (e.g., conflict detection) will be performed when
039 * the method is executed.
040 * </p>
041 *
042 * @param src the source node of the edge
043 * @param dst the destination node of the edge
044 * @param data information to be stored in the new edge
045 * @return true if there was no previous edge between the two nodes
046 */
047 public boolean addEdge(GNode<N> src, GNode<N> dst, long data);
048
049 /**
050 * Adds an edge to the graph containing the specified data.
051 *
052 * @param src the source node of the edge
053 * @param dst the destination node of the edge
054 * @param data information to be stored in the new edge
055 * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
056 * upon invocation of this method. See {@link galois.objects.MethodFlag}
057 * @return true if there was no previous edge between the two nodes
058 */
059 public boolean addEdge(GNode<N> src, GNode<N> dst, long data, byte flags);
060
061 /**
062 * Retrieves the data associated with an edge.
063 * <p>
064 * Be aware that this method will return -1 in two cases:
065 * </p>
066 * <ul>
067 * <li> there is no edge between the two nodes
068 * <li> there is an edge between the two nodes, and its data is -1
069 * </ul>
070 * <p>
071 * In order to distinguish between the two cases, use {@link Graph#hasNeighbor(GNode, GNode)}
072 * </p>
073 * <p>
074 * All the Galois runtime actions (e.g., conflict detection) will be performed when
075 * the method is executed.
076 * </p>
077 *
078 * @param src the source node of the edge
079 * @param dst the destination node of the edge
080 * @return the data associated with the edge, or -1 if the edge does not exist
081 */
082 public long getEdgeData(GNode<N> src, GNode<N> dst);
083
084 /**
085 * Retrieves the data associated with an edge.
086 * <p>
087 * Be aware that this method will return -1 in two cases:
088 * </p>
089 * <ul>
090 * <li> there is no edge between the two nodes
091 * <li> there is an edge between the two nodes, and its data is -1
092 * </ul>
093 * <p>
094 * In order to distinguish between the two cases, use {@link Graph#hasNeighbor(GNode, GNode)}
095 * </p>
096 * @param src the source node of the edge
097 * @param dst the destination node of the edge
098 * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
099 * upon invocation of this method. See {@link galois.objects.MethodFlag}
100 * @return the data associated with the edge, or -1 if the edge does not exist
101 */
102 public long getEdgeData(GNode<N> src, GNode<N> dst, byte flags);
103
104 /**
105 * Sets the data associated with an edge.
106 * <p>
107 * All the Galois runtime actions (e.g., conflict detection) will be performed when
108 * the method is executed.
109 * </p>
110 * @param src the source node of the edge
111 * @param dst the destination node of the edge
112 * @param d the data to associate with the edge
113 * @return the data previously associated with the edge, or -1 if the edge does not exist
114 */
115 public long setEdgeData(GNode<N> src, GNode<N> dst, long d);
116
117 /**
118 * Sets the data associated with an edge.
119 *
120 * @param src the source node of the edge
121 * @param dst the destination node of the edge
122 * @param d the data to associate with the edge
123 * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
124 * upon invocation of this method. See {@link galois.objects.MethodFlag}
125 * @return the data previously associated with the edge, or -1 if the edge does not exist
126 */
127 public long setEdgeData(GNode<N> src, GNode<N> dst, long d, byte flags);
128 }