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
Pipeline #9682 passed with stages
in 446 minutes and 52 seconds
......@@ -102,14 +102,13 @@ import GHC.Types
-- it; if you have data that lives in two 'Compact's, each will have a
-- separate copy of the data.
--
-- The cost of compaction is similar to the cost of GC for the same
-- data, but it is performed only once. However, because
-- "GHC.Compact.compact" does not stop-the-world, retaining internal
-- sharing during the compaction process is very costly. The user
-- can choose whether to 'compact' or 'compactWithSharing'.
-- The cost of compaction is fully evaluating the data + copying it. However,
-- because 'compact' does not stop-the-world, retaining internal sharing during
-- the compaction process is very costly. The user can choose whether to
-- 'compact' or 'compactWithSharing'.
--
-- 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
-- to add data to a specific 'Compact' with 'compactAdd' or
-- 'compactAddWithSharing' (giving you a new handle which corresponds
......@@ -134,7 +133,7 @@ import GHC.Types
-- 'GHC.Array.MutableArray') also cannot be compacted, because subsequent
-- 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.
--
data Compact a = Compact Compact# a (MVar ())
......@@ -155,12 +154,16 @@ mkCompact compact# a s =
where
unIO (IO a) = a
-- | Transfer @a@ into a new compact region, with a preallocated size,
-- possibly preserving sharing or not. If you know how big the data
-- structure in question is, you can save time by picking an appropriate
-- block size for the compact region.
--
compactSized :: Int -> Bool -> a -> IO (Compact a)
-- | Transfer @a@ into a new compact region, with a preallocated size (in
-- 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 block
-- size for the compact region.
--
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 ->
case compactNew# (int2Word# size) s0 of { (# s1, compact# #) ->
case compactAddPrim compact# a s1 of { (# s2, pk #) ->
......@@ -254,7 +257,7 @@ compactSize :: Compact a -> IO Word
compactSize (Compact buffer _ lock) = withMVar lock $ \_ -> IO $ \s0 ->
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
-- when the current block runs out of space, and also appends a block
-- 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