add comments for orderedSet

Author: soulomoon

ghcide/session-loader/Development/IDE/Session.hs

@@ -509,7 +509,7 @@ incrementVersion state = modifyVar' (version state) succ
 
 -- | Get files from the pending file set
 getPendingFiles :: SessionState -> IO (HashSet FilePath)
-getPendingFiles state = atomically $ Set.fromList <$> S.toUnOrderedList (pendingFiles state)
+getPendingFiles state = atomically $ S.toHashSet (pendingFiles state)
 
 -- | Handle errors during session loading by recording file as having error and removing from pending
 handleSingleFileProcessingError' :: SessionState -> Maybe FilePath -> FilePath -> PackageSetupException -> SessionM ()

ghcide/session-loader/Development/IDE/Session/OrderedSet.hs

@@ -5,6 +5,7 @@ import           Control.Concurrent.STM        (STM, TQueue, flushTQueue,
 import           Control.Concurrent.STM.TQueue (readTQueue, writeTQueue)
 import           Control.Monad                 (when)
 import           Data.Hashable                 (Hashable)
+import qualified Data.HashSet
 import qualified Focus
 import qualified ListT                         as LT
 import qualified StmContainers.Set             as S
@@ -13,6 +14,14 @@ import           StmContainers.Set             (Set)
 
 type OrderedSet a = (TQueue a, Set a)
 
+-- | Insert an element into the ordered set.
+-- If the element is not already present, it is added to both the queue and set.
+-- If the element already exists, it is moved to the end of the queue to maintain
+-- most-recently-inserted ordering semantics.
+-- It take O(n), not very good.
+
+-- Alternative: could preserve original position.
+-- I am not sure which one is better.
 insert :: Hashable a => a -> OrderedSet a -> STM ()
 insert a (que, s) = do
     (_, inserted) <- S.focus (Focus.testingIfInserts $ Focus.insert ()) a s
@@ -23,14 +32,16 @@ insert a (que, s) = do
             mapM_ (writeTQueue que) items
             return ()
     writeTQueue que a
-            -- when que $ writeTQueue que a
 
 newIO :: Hashable a => IO (OrderedSet a)
 newIO = do
     que <- newTQueueIO
     s <- S.newIO
     return (que, s)
 
+-- | Read the first element from the queue.
+-- If an element is not in the set, it means it has been deleted,
+-- so we retry until we find a valid element that exists in the set.
 readQueue :: Hashable a => OrderedSet a -> STM a
 readQueue rs@(que, s) = do
                 f <- readTQueue que
@@ -41,8 +52,11 @@ readQueue rs@(que, s) = do
 lookup :: Hashable a => a -> OrderedSet a -> STM Bool
 lookup a (_, s) = S.lookup a s
 
+-- | Delete an element from the set.
+-- The queue is not modified directly; stale entries are filtered out lazily
+-- during reading operations (see 'readQueue').
 delete :: Hashable a => a -> OrderedSet a -> STM ()
 delete a (_, s) = S.delete a s
 
-toUnOrderedList :: Hashable a => OrderedSet a -> STM [a]
-toUnOrderedList (_, s) = LT.toList $ S.listT s
+toHashSet :: Hashable a => OrderedSet a -> Data.HashSet a
+toHashSet (_, s) = TreeSet.fromList $ LT.toList $ S.listT s