    -- | Basic operations on graphs.
    --

    module GraphOps (
            addNode,        delNode,        getNode,       lookupNode,     modNode,
            size,
            union,
            addConflict,    delConflict,    addConflicts,
            addCoalesce,    delCoalesce,
            addExclusion,   addExclusions,
            addPreference,
            coalesceNodes,  coalesceGraph,
            freezeNode,     freezeOneInGraph, freezeAllInGraph,
            scanGraph,
            setColor,
            validateGraph,
            slurpNodeConflictCount
    )
    where

    import GhcPrelude

    import GraphBase

    import Outputable
    import Unique
    import UniqSet
    import UniqFM

    import Data.List        hiding (union)
    import Data.Maybe

    -- | Lookup a node from the graph.
    lookupNode
            :: Uniquable k
            => Graph k cls color
            -> k -> Maybe (Node  k cls color)

    lookupNode graph k
            = lookupUFM (graphMap graph) k

    -- | Get a node from the graph, throwing an error if it's not there
    getNode
            :: Uniquable k
            => Graph k cls color
            -> k -> Node k cls color

    getNode graph k
     = case lookupUFM (graphMap graph) k of
            Just node       -> node
            Nothing         -> panic "ColorOps.getNode: not found"

    -- | Add a node to the graph, linking up its edges
    addNode :: Uniquable k
            => k -> Node k cls color
            -> Graph k cls color -> Graph k cls color

    addNode k node graph
     = let
            -- add back conflict edges from other nodes to this one
            map_conflict =
              nonDetFoldUniqSet
                -- It's OK to use nonDetFoldUFM here because the
                -- operation is commutative
                (adjustUFM_C (\n -> n { nodeConflicts =
                                          addOneToUniqSet (nodeConflicts n) k}))
                (graphMap graph)
                (nodeConflicts node)

            -- add back coalesce edges from other nodes to this one
            map_coalesce =
              nonDetFoldUniqSet
                -- It's OK to use nonDetFoldUFM here because the
                -- operation is commutative
                (adjustUFM_C (\n -> n { nodeCoalesce =
                                          addOneToUniqSet (nodeCoalesce n) k}))
                map_conflict
                (nodeCoalesce node)

      in    graph
            { graphMap      = addToUFM map_coalesce k node}

    -- | Delete a node and all its edges from the graph.
    delNode :: (Uniquable k)
            => k -> Graph k cls color -> Maybe (Graph k cls color)

    delNode k graph
            | Just node     <- lookupNode graph k
            = let   -- delete conflict edges from other nodes to this one.
                    graph1  = foldl' (\g k1 -> let Just g' = delConflict k1 k g in g') graph
                            $ nonDetEltsUniqSet (nodeConflicts node)

                    -- delete coalesce edge from other nodes to this one.
                    graph2  = foldl' (\g k1 -> let Just g' = delCoalesce k1 k g in g') graph1
                            $ nonDetEltsUniqSet (nodeCoalesce node)
                            -- See Note [Unique Determinism and code generation]

                    -- delete the node
                    graph3  = graphMapModify (\fm -> delFromUFM fm k) graph2

              in    Just graph3

            | otherwise
            = Nothing

    -- | Modify a node in the graph.
    --      returns Nothing if the node isn't present.
    --
    modNode :: Uniquable k
            => (Node k cls color -> Node k cls color)
            -> k -> Graph k cls color -> Maybe (Graph k cls color)

    modNode f k graph
     = case lookupNode graph k of
            Just Node{}
             -> Just
             $  graphMapModify
                     (\fm   -> let  Just node       = lookupUFM fm k
                                    node'           = f node
                               in   addToUFM fm k node')
                    graph

            Nothing -> Nothing

    -- | Get the size of the graph, O(n)
    size    :: Graph k cls color -> Int

    size graph
            = sizeUFM $ graphMap graph

    -- | Union two graphs together.
    union   :: Graph k cls color -> Graph k cls color -> Graph k cls color

    union   graph1 graph2
            = Graph
            { graphMap              = plusUFM (graphMap graph1) (graphMap graph2) }

    -- | Add a conflict between nodes to the graph, creating the nodes required.
    --      Conflicts are virtual regs which need to be colored differently.
    addConflict
            :: Uniquable k
            => (k, cls) -> (k, cls)
            -> Graph k cls color -> Graph k cls color

    addConflict (u1, c1) (u2, c2)
     = let  addNeighbor u c u'
                    = adjustWithDefaultUFM
                            (\node -> node { nodeConflicts = addOneToUniqSet (nodeConflicts node) u' })
                            (newNode u c)  { nodeConflicts = unitUniqSet u' }
                            u

       in   graphMapModify
            ( addNeighbor u1 c1 u2
            . addNeighbor u2 c2 u1)

    -- | Delete a conflict edge. k1 -> k2
    --      returns Nothing if the node isn't in the graph
    delConflict
            :: Uniquable k
            => k -> k
            -> Graph k cls color -> Maybe (Graph k cls color)

    delConflict k1 k2
            = modNode
                    (\node -> node { nodeConflicts = delOneFromUniqSet (nodeConflicts node) k2 })
                    k1

    -- | Add some conflicts to the graph, creating nodes if required.
    --      All the nodes in the set are taken to conflict with each other.
    addConflicts
            :: Uniquable k
            => UniqSet k -> (k -> cls)
            -> Graph k cls color -> Graph k cls color

    addConflicts conflicts getClass

            -- just a single node, but no conflicts, create the node anyway.
            | (u : [])      <- nonDetEltsUniqSet conflicts
            = graphMapModify
            $ adjustWithDefaultUFM
                    id
                    (newNode u (getClass u))
                    u

            | otherwise
            = graphMapModify
            $ \fm -> foldl' (\g u  -> addConflictSet1 u getClass conflicts g) fm
                    $ nonDetEltsUniqSet conflicts
                    -- See Note [Unique Determinism and code generation]

    addConflictSet1 :: Uniquable k
                    => k -> (k -> cls) -> UniqSet k
                    -> UniqFM (Node k cls color)
                    -> UniqFM (Node k cls color)
    addConflictSet1 u getClass set
     = case delOneFromUniqSet set u of
        set' -> adjustWithDefaultUFM
                    (\node -> node                  { nodeConflicts = unionUniqSets set' (nodeConflicts node) } )
                    (newNode u (getClass u))        { nodeConflicts = set' }
                    u

    -- | Add an exclusion to the graph, creating nodes if required.
    --      These are extra colors that the node cannot use.
    addExclusion
            :: (Uniquable k, Uniquable color)
            => k -> (k -> cls) -> color
            -> Graph k cls color -> Graph k cls color

    addExclusion u getClass color
            = graphMapModify
            $ adjustWithDefaultUFM
                    (\node -> node                  { nodeExclusions = addOneToUniqSet (nodeExclusions node) color })
                    (newNode u (getClass u))        { nodeExclusions = unitUniqSet color }
                    u

    addExclusions
            :: (Uniquable k, Uniquable color)
            => k -> (k -> cls) -> [color]
            -> Graph k cls color -> Graph k cls color

    addExclusions u getClass colors graph
            = foldr (addExclusion u getClass) graph colors

    -- | Add a coalescence edge to the graph, creating nodes if requried.
    --      It is considered adventageous to assign the same color to nodes in a coalesence.
    addCoalesce
            :: Uniquable k
            => (k, cls) -> (k, cls)
            -> Graph k cls color -> Graph k cls color

    addCoalesce (u1, c1) (u2, c2)
     = let  addCoalesce u c u'
             =      adjustWithDefaultUFM
                            (\node -> node { nodeCoalesce = addOneToUniqSet (nodeCoalesce node) u' })
                            (newNode u c)  { nodeCoalesce = unitUniqSet u' }
                            u

       in   graphMapModify
            ( addCoalesce u1 c1 u2
            . addCoalesce u2 c2 u1)

    -- | Delete a coalescence edge (k1 -> k2) from the graph.
    delCoalesce
            :: Uniquable k
            => k -> k
            -> Graph k cls color    -> Maybe (Graph k cls color)

    delCoalesce k1 k2
            = modNode (\node -> node { nodeCoalesce = delOneFromUniqSet (nodeCoalesce node) k2 })
                    k1

    -- | Add a color preference to the graph, creating nodes if required.
    --      The most recently added preference is the most prefered.
    --      The algorithm tries to assign a node it's prefered color if possible.
    --
    addPreference
            :: Uniquable k
            => (k, cls) -> color
            -> Graph k cls color -> Graph k cls color

    addPreference (u, c) color
            = graphMapModify
            $ adjustWithDefaultUFM
                    (\node -> node { nodePreference = color : (nodePreference node) })
                    (newNode u c)  { nodePreference = [color] }
                    u

    -- | Do aggressive coalescing on this graph.
    --      returns the new graph and the list of pairs of nodes that got coalesced together.
    --      for each pair, the resulting node will have the least key and be second in the pair.
    --
    coalesceGraph
            :: (Uniquable k, Ord k, Eq cls, Outputable k)
            => Bool                 -- ^ If True, coalesce nodes even if this might make the graph
                                    --      less colorable (aggressive coalescing)
            -> Triv k cls color
            -> Graph k cls color
            -> ( Graph k cls color
               , [(k, k)])          -- pairs of nodes that were coalesced, in the order that the
                                    --      coalescing was applied.

    coalesceGraph aggressive triv graph
            = coalesceGraph' aggressive triv graph []

    coalesceGraph'
            :: (Uniquable k, Ord k, Eq cls, Outputable k)
            => Bool
            -> Triv k cls color
            -> Graph k cls color
            -> [(k, k)]
            -> ( Graph k cls color
               , [(k, k)])
    coalesceGraph' aggressive triv graph kkPairsAcc
     = let
            -- find all the nodes that have coalescence edges
            cNodes  = filter (\node -> not $ isEmptyUniqSet (nodeCoalesce node))
                    $ nonDetEltsUFM $ graphMap graph
                    -- See Note [Unique Determinism and code generation]

            -- build a list of pairs of keys for node's we'll try and coalesce
            --      every pair of nodes will appear twice in this list
            --      ie [(k1, k2), (k2, k1) ... ]
            --      This is ok, GrapOps.coalesceNodes handles this and it's convenient for
            --      build a list of what nodes get coalesced together for later on.
            --
            cList   = [ (nodeId node1, k2)
                            | node1 <- cNodes
                            , k2    <- nonDetEltsUniqSet $ nodeCoalesce node1 ]
                            -- See Note [Unique Determinism and code generation]

            -- do the coalescing, returning the new graph and a list of pairs of keys
            --      that got coalesced together.
            (graph', mPairs)
                    = mapAccumL (coalesceNodes aggressive triv) graph cList

            -- keep running until there are no more coalesces can be found
       in   case catMaybes mPairs of
             []     -> (graph', reverse kkPairsAcc)
             pairs  -> coalesceGraph' aggressive triv graph' (reverse pairs ++ kkPairsAcc)

    -- | Coalesce this pair of nodes unconditionally \/ aggressively.
    --      The resulting node is the one with the least key.
    --
    --      returns: Just    the pair of keys if the nodes were coalesced
    --                       the second element of the pair being the least one
    --
    --               Nothing if either of the nodes weren't in the graph

    coalesceNodes
            :: (Uniquable k, Ord k, Eq cls)
            => Bool                 -- ^ If True, coalesce nodes even if this might make the graph
                                    --      less colorable (aggressive coalescing)
            -> Triv  k cls color
            -> Graph k cls color
            -> (k, k)               -- ^ keys of the nodes to be coalesced
            -> (Graph k cls color, Maybe (k, k))

    coalesceNodes aggressive triv graph (k1, k2)
            | (kMin, kMax)  <- if k1 < k2
                                    then (k1, k2)
                                    else (k2, k1)

            -- the nodes being coalesced must be in the graph
            , Just nMin     <- lookupNode graph kMin
            , Just nMax     <- lookupNode graph kMax

            -- can't coalesce conflicting modes
            , not $ elementOfUniqSet kMin (nodeConflicts nMax)
            , not $ elementOfUniqSet kMax (nodeConflicts nMin)

            -- can't coalesce the same node
            , nodeId nMin /= nodeId nMax

            = coalesceNodes_merge aggressive triv graph kMin kMax nMin nMax

            -- don't do the coalescing after all
            | otherwise
            = (graph, Nothing)

    coalesceNodes_merge
            :: (Uniquable k, Eq cls)
            => Bool
            -> Triv  k cls color
            -> Graph k cls color
            -> k -> k
            -> Node k cls color
            -> Node k cls color
            -> (Graph k cls color, Maybe (k, k))

    coalesceNodes_merge aggressive triv graph kMin kMax nMin nMax

            -- sanity checks
            | nodeClass nMin /= nodeClass nMax
            = error "GraphOps.coalesceNodes: can't coalesce nodes of different classes."

            | not (isNothing (nodeColor nMin) && isNothing (nodeColor nMax))
            = error "GraphOps.coalesceNodes: can't coalesce colored nodes."

            ---
            | otherwise
            = let
                    -- the new node gets all the edges from its two components
                    node    =
                     Node   { nodeId                = kMin
                            , nodeClass             = nodeClass nMin
                            , nodeColor             = Nothing

                            -- nodes don't conflict with themselves..
                            , nodeConflicts
                                    = (unionUniqSets (nodeConflicts nMin) (nodeConflicts nMax))
                                            `delOneFromUniqSet` kMin
                                            `delOneFromUniqSet` kMax

                            , nodeExclusions        = unionUniqSets (nodeExclusions nMin) (nodeExclusions nMax)
                            , nodePreference        = nodePreference nMin ++ nodePreference nMax

                            -- nodes don't coalesce with themselves..
                            , nodeCoalesce
                                    = (unionUniqSets (nodeCoalesce nMin) (nodeCoalesce nMax))
                                            `delOneFromUniqSet` kMin
                                            `delOneFromUniqSet` kMax
                            }

              in    coalesceNodes_check aggressive triv graph kMin kMax node

    coalesceNodes_check
            :: Uniquable k
            => Bool
            -> Triv  k cls color
            -> Graph k cls color
            -> k -> k
            -> Node k cls color
            -> (Graph k cls color, Maybe (k, k))

    coalesceNodes_check aggressive triv graph kMin kMax node

            -- Unless we're coalescing aggressively, if the result node is not trivially
            --      colorable then don't do the coalescing.
            | not aggressive
            , not $ triv (nodeClass node) (nodeConflicts node) (nodeExclusions node)
            = (graph, Nothing)

            | otherwise
            = let -- delete the old nodes from the graph and add the new one
                    Just graph1     = delNode kMax graph
                    Just graph2     = delNode kMin graph1
                    graph3          = addNode kMin node graph2

              in    (graph3, Just (kMax, kMin))

    -- | Freeze a node
    --      This is for the iterative coalescer.
    --      By freezing a node we give up on ever coalescing it.
    --      Move all its coalesce edges into the frozen set - and update
    --      back edges from other nodes.
    --
    freezeNode
            :: Uniquable k
            => k                    -- ^ key of the node to freeze
            -> Graph k cls color    -- ^ the graph
            -> Graph k cls color    -- ^ graph with that node frozen

    freezeNode k
      = graphMapModify
      $ \fm ->
        let -- freeze all the edges in the node to be frozen
            Just node = lookupUFM fm k
            node'   = node
                    { nodeCoalesce          = emptyUniqSet }

            fm1     = addToUFM fm k node'

            -- update back edges pointing to this node
            freezeEdge k node
             = if elementOfUniqSet k (nodeCoalesce node)
                    then node { nodeCoalesce = delOneFromUniqSet (nodeCoalesce node) k }
                    else node       -- panic "GraphOps.freezeNode: edge to freeze wasn't in the coalesce set"
                                    -- If the edge isn't actually in the coelesce set then just ignore it.

            fm2     = nonDetFoldUniqSet (adjustUFM_C (freezeEdge k)) fm1
                        -- It's OK to use nonDetFoldUFM here because the operation
                        -- is commutative
                            $ nodeCoalesce node

        in  fm2

    -- | Freeze one node in the graph
    --      This if for the iterative coalescer.
    --      Look for a move related node of low degree and freeze it.
    --
    --      We probably don't need to scan the whole graph looking for the node of absolute
    --      lowest degree. Just sample the first few and choose the one with the lowest
    --      degree out of those. Also, we don't make any distinction between conflicts of different
    --      classes.. this is just a heuristic, after all.
    --
    --      IDEA:   freezing a node might free it up for Simplify.. would be good to check for triv
    --              right here, and add it to a worklist if known triv\/non-move nodes.
    --
    freezeOneInGraph
            :: (Uniquable k)
            => Graph k cls color
            -> ( Graph k cls color          -- the new graph
               , Bool )                     -- whether we found a node to freeze

    freezeOneInGraph graph
     = let  compareNodeDegree n1 n2
                    = compare (sizeUniqSet $ nodeConflicts n1) (sizeUniqSet $ nodeConflicts n2)

            candidates
                    = sortBy compareNodeDegree
                    $ take 5        -- 5 isn't special, it's just a small number.
                    $ scanGraph (\node -> not $ isEmptyUniqSet (nodeCoalesce node)) graph

       in   case candidates of

             -- there wasn't anything available to freeze
             []     -> (graph, False)

             -- we found something to freeze
             (n : _)
              -> ( freezeNode (nodeId n) graph
                 , True)

    -- | Freeze all the nodes in the graph
    --      for debugging the iterative allocator.
    --
    freezeAllInGraph
            :: (Uniquable k)
            => Graph k cls color
            -> Graph k cls color

    freezeAllInGraph graph
            = foldr freezeNode graph
                    $ map nodeId
                    $ nonDetEltsUFM $ graphMap graph
                    -- See Note [Unique Determinism and code generation]

    -- | Find all the nodes in the graph that meet some criteria
    --
    scanGraph
            :: (Node k cls color -> Bool)
            -> Graph k cls color
            -> [Node k cls color]

    scanGraph match graph
            = filter match $ nonDetEltsUFM $ graphMap graph
              -- See Note [Unique Determinism and code generation]

    -- | validate the internal structure of a graph
    --      all its edges should point to valid nodes
    --      If they don't then throw an error
    --
    validateGraph
            :: (Uniquable k, Outputable k, Eq color)
            => SDoc                         -- ^ extra debugging info to display on error
            -> Bool                         -- ^ whether this graph is supposed to be colored.
            -> Graph k cls color            -- ^ graph to validate
            -> Graph k cls color            -- ^ validated graph

    validateGraph doc isColored graph

            -- Check that all edges point to valid nodes.
            | edges         <- unionManyUniqSets
                                    (  (map nodeConflicts       $ nonDetEltsUFM $ graphMap graph)
                                    ++ (map nodeCoalesce        $ nonDetEltsUFM $ graphMap graph))

            , nodes         <- mkUniqSet $ map nodeId $ nonDetEltsUFM $ graphMap graph
            , badEdges      <- minusUniqSet edges nodes
            , not $ isEmptyUniqSet badEdges
            = pprPanic "GraphOps.validateGraph"
                    (  text "Graph has edges that point to non-existent nodes"
                    $$ text "  bad edges: " <> pprUFM (getUniqSet badEdges) (vcat . map ppr)
                    $$ doc )

            -- Check that no conflicting nodes have the same color
            | badNodes      <- filter (not . (checkNode graph))
                            $ nonDetEltsUFM $ graphMap graph
                               -- See Note [Unique Determinism and code generation]
            , not $ null badNodes
            = pprPanic "GraphOps.validateGraph"
                    (  text "Node has same color as one of it's conflicts"
                    $$ text "  bad nodes: " <> hcat (map (ppr . nodeId) badNodes)
                    $$ doc)

            -- If this is supposed to be a colored graph,
            --      check that all nodes have a color.
            | isColored
            , badNodes      <- filter (\n -> isNothing $ nodeColor n)
                            $  nonDetEltsUFM $ graphMap graph
            , not $ null badNodes
            = pprPanic "GraphOps.validateGraph"
                    (  text "Supposably colored graph has uncolored nodes."
                    $$ text "  uncolored nodes: " <> hcat (map (ppr . nodeId) badNodes)
                    $$ doc )

            -- graph looks ok
            | otherwise
            = graph

    -- | If this node is colored, check that all the nodes which
    --      conflict with it have different colors.
    checkNode
            :: (Uniquable k, Eq color)
            => Graph k cls color
            -> Node  k cls color
            -> Bool                 -- ^ True if this node is ok

    checkNode graph node
            | Just color            <- nodeColor node
            , Just neighbors        <- sequence $ map (lookupNode graph)
                                    $  nonDetEltsUniqSet $ nodeConflicts node
                -- See Note [Unique Determinism and code generation]

            , neighbourColors       <- catMaybes $ map nodeColor neighbors
            , elem color neighbourColors
            = False

            | otherwise
            = True

    -- | Slurp out a map of how many nodes had a certain number of conflict neighbours

    slurpNodeConflictCount
            :: Graph k cls color
            -> UniqFM (Int, Int)    -- ^ (conflict neighbours, num nodes with that many conflicts)

    slurpNodeConflictCount graph
            = addListToUFM_C
                    (\(c1, n1) (_, n2) -> (c1, n1 + n2))
                    emptyUFM
            $ map   (\node
                      -> let count  = sizeUniqSet $ nodeConflicts node
                         in  (count, (count, 1)))
            $ nonDetEltsUFM
            -- See Note [Unique Determinism and code generation]
            $ graphMap graph

    -- | Set the color of a certain node
    setColor
            :: Uniquable k
            => k -> color
            -> Graph k cls color -> Graph k cls color

    setColor u color
            = graphMapModify
            $ adjustUFM_C
                    (\n -> n { nodeColor = Just color })
                    u

    {-# INLINE adjustWithDefaultUFM #-}
    adjustWithDefaultUFM
            :: Uniquable k
            => (a -> a) -> a -> k
            -> UniqFM a -> UniqFM a

    adjustWithDefaultUFM f def k map
            = addToUFM_C
                    (\old _ -> f old)
                    map
                    k def

    -- Argument order different from UniqFM's adjustUFM
    {-# INLINE adjustUFM_C #-}
    adjustUFM_C
            :: Uniquable k
            => (a -> a)
            -> k -> UniqFM a -> UniqFM a

    adjustUFM_C f k map
     = case lookupUFM map k of
            Nothing -> map
            Just a  -> addToUFM map k (f a)