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: IndexedGraph.java 
019    
020     */
021    
022    package galois.objects.graph;
023    
024    import galois.objects.GObject;
025    
026    /**
027     * This interface represents a graph that allows programmers to refer to a
028     * node's edges by a particular index. An indexed graph is always directed, and
029     * does not contain any information on the edges.
030     *
031     * @param <N> type of the data contained in a node
032     */
033    public interface IndexedGraph<N extends GObject> extends Graph<N> {
034    
035      /**
036       * Set a particular neighbor of a given node.
037       *
038       * All the Galois runtime actions (e.g., conflict detection) will be performed when
039       * the method is executed.
040       *
041       * @param src   the node whose neighbor to set
042       * @param dst  the new neighbor
043       * @param index the particular neighbor to set
044       */
045      public void setNeighbor(GNode<N> src, GNode<N> dst, int index);
046    
047      /**
048       * Set a particular neighbor of a given node.
049       *
050       * @param src   the node whose neighbor to set
051       * @param dst  the new neighbor
052       * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
053       *              upon invocation of this method. See {@link galois.objects.MethodFlag}
054       * @param index the particular neighbor to set
055       */
056      public void setNeighbor(GNode<N> src, GNode<N> dst, int index, byte flags);
057    
058      /**
059       * Get a particular neighbor of a given node
060       *
061       * All the Galois runtime actions (e.g., conflict detection) will be performed when
062       * the method is executed.
063       *
064       * @param src   the node whose neighbor to get
065       * @param index the particular neighbor to get
066       * @return the neighbor at index
067       */
068      public GNode<N> getNeighbor(GNode<N> src, int index);
069    
070      /**
071       * Get a particular neighbor of a given node
072       *
073       * @param src   the node whose neighbor to get
074       * @param index the particular neighbor to get
075       * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
076       *              upon invocation of this method. See {@link galois.objects.MethodFlag}
077       * @return the neighbor at index
078       */
079      public GNode<N> getNeighbor(GNode<N> src, int index, byte flags);
080    
081      /**
082       * Remove a particular neighbor of a given node. Note that this is equivalent
083       * to calling setNeighbor(src, null, index)
084       *
085       * All the Galois runtime actions (e.g., conflict detection) will be performed when
086       * the method is executed.
087       *
088       * @param src   the node whose neighbor to remove
089       * @param index the neighbor to remove
090       * @return true if the neighbor was successfully removed
091       */
092      public boolean removeNeighbor(GNode<N> src, int index);
093    
094      /**
095       * Remove a particular neighbor of a given node. Note that this is equivalent
096       * to calling setNeighbor(src, null, index)
097       *
098       * @param src   the node whose neighbor to remove
099       * @param index the neighbor to remove
100       * @param flags Galois runtime actions (e.g., conflict detection) that need to be executed
101       *              upon invocation of this method. See {@link galois.objects.MethodFlag}
102       * @return true if the neighbor was successfully removed
103       */
104      public boolean removeNeighbor(GNode<N> src, int index, byte flags);
105    }