Commit 89487be2 authored by Ömer Sinan Ağacan's avatar Ömer Sinan Ağacan Committed by Marge Bot

Some tweaks in GHC.Compact haddocks

parent 10763ce0
...@@ -102,14 +102,13 @@ import GHC.Types ...@@ -102,14 +102,13 @@ import GHC.Types
-- it; if you have data that lives in two 'Compact's, each will have a -- it; if you have data that lives in two 'Compact's, each will have a
-- separate copy of the data. -- separate copy of the data.
-- --
-- The cost of compaction is similar to the cost of GC for the same -- The cost of compaction is fully evaluating the data + copying it. However,
-- data, but it is performed only once. However, because -- because 'compact' does not stop-the-world, retaining internal sharing during
-- "GHC.Compact.compact" does not stop-the-world, retaining internal -- the compaction process is very costly. The user can choose whether to
-- sharing during the compaction process is very costly. The user -- 'compact' or 'compactWithSharing'.
-- can choose whether to 'compact' or 'compactWithSharing'.
-- --
-- When you have a @'Compact' a@, you can get a pointer to the actual object -- When you have a @'Compact' a@, you can get a pointer to the actual object
-- in the region using "GHC.Compact.getCompact". The 'Compact' type -- in the region using 'getCompact'. The 'Compact' type
-- serves as handle on the region itself; you can use this handle -- serves as handle on the region itself; you can use this handle
-- to add data to a specific 'Compact' with 'compactAdd' or -- to add data to a specific 'Compact' with 'compactAdd' or
-- 'compactAddWithSharing' (giving you a new handle which corresponds -- 'compactAddWithSharing' (giving you a new handle which corresponds
...@@ -134,7 +133,7 @@ import GHC.Types ...@@ -134,7 +133,7 @@ import GHC.Types
-- 'GHC.Array.MutableArray') also cannot be compacted, because subsequent -- 'GHC.Array.MutableArray') also cannot be compacted, because subsequent
-- mutation would destroy the property that a compact is self-contained. -- mutation would destroy the property that a compact is self-contained.
-- --
-- If compaction encounters any of the above, a 'CompactionFailed' -- If compaction encounters any of the above, a 'Control.Exception.CompactionFailed'
-- exception will be thrown by the compaction operation. -- exception will be thrown by the compaction operation.
-- --
data Compact a = Compact Compact# a (MVar ()) data Compact a = Compact Compact# a (MVar ())
...@@ -155,12 +154,16 @@ mkCompact compact# a s = ...@@ -155,12 +154,16 @@ mkCompact compact# a s =
where where
unIO (IO a) = a unIO (IO a) = a
-- | Transfer @a@ into a new compact region, with a preallocated size, -- | Transfer @a@ into a new compact region, with a preallocated size (in
-- possibly preserving sharing or not. If you know how big the data -- bytes), possibly preserving sharing or not. If you know how big the data
-- structure in question is, you can save time by picking an appropriate -- structure in question is, you can save time by picking an appropriate block
-- block size for the compact region. -- size for the compact region.
-- --
compactSized :: Int -> Bool -> a -> IO (Compact a) compactSized
:: Int -- ^ Size of the compact region, in bytes
-> Bool -- ^ Whether to retain internal sharing
-> a
-> IO (Compact a)
compactSized (I# size) share a = IO $ \s0 -> compactSized (I# size) share a = IO $ \s0 ->
case compactNew# (int2Word# size) s0 of { (# s1, compact# #) -> case compactNew# (int2Word# size) s0 of { (# s1, compact# #) ->
case compactAddPrim compact# a s1 of { (# s2, pk #) -> case compactAddPrim compact# a s1 of { (# s2, pk #) ->
...@@ -254,7 +257,7 @@ compactSize :: Compact a -> IO Word ...@@ -254,7 +257,7 @@ compactSize :: Compact a -> IO Word
compactSize (Compact buffer _ lock) = withMVar lock $ \_ -> IO $ \s0 -> compactSize (Compact buffer _ lock) = withMVar lock $ \_ -> IO $ \s0 ->
case compactSize# buffer s0 of (# s1, sz #) -> (# s1, W# sz #) case compactSize# buffer s0 of (# s1, sz #) -> (# s1, W# sz #)
-- | *Experimental.* This function doesn't actually resize a compact -- | __Experimental__ This function doesn't actually resize a compact
-- region; rather, it changes the default block size which we allocate -- region; rather, it changes the default block size which we allocate
-- when the current block runs out of space, and also appends a block -- when the current block runs out of space, and also appends a block
-- to the compact region. -- to the compact region.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment