thread-utils-context (empty) → 0.1.0.0

raw patch · 7 files changed

+283/−0 lines, 7 filesdep +basedep +containersdep +ghc-primsetup-changed

Dependencies added: base, containers, ghc-prim, thread-utils-context, thread-utils-finalizers

Files

ChangeLog.md +3/−0
LICENSE +30/−0
README.md +1/−0
Setup.hs +2/−0
src/Control/Concurrent/Thread/Storage.hs +166/−0
test/Spec.hs +25/−0
thread-utils-context.cabal +56/−0

+ ChangeLog.md view

@@ -0,0 +1,3 @@+# Changelog for thread-utils-context++## Unreleased changes

+ LICENSE view

@@ -0,0 +1,30 @@+Copyright Ian Duncan (c) 2021++All rights reserved.++Redistribution and use in source and binary forms, with or without+modification, are permitted provided that the following conditions are met:++    * Redistributions of source code must retain the above copyright+      notice, this list of conditions and the following disclaimer.++    * Redistributions in binary form must reproduce the above+      copyright notice, this list of conditions and the following+      disclaimer in the documentation and/or other materials provided+      with the distribution.++    * Neither the name of Ian Duncan nor the names of other+      contributors may be used to endorse or promote products derived+      from this software without specific prior written permission.++THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+ README.md view

@@ -0,0 +1,1 @@+# thread-utils-context

+ Setup.hs view

@@ -0,0 +1,2 @@+import Distribution.Simple+main = defaultMain

+ src/Control/Concurrent/Thread/Storage.hs view

@@ -0,0 +1,166 @@+{-# LANGUAGE MagicHash #-}+{-# LANGUAGE UnliftedFFITypes #-}+{-# LANGUAGE UnboxedTuples #-}+-- | A perilous implementation of thread-local storage for Haskell.+-- This module uses a fair amount of GHC internals to enable performing+-- lookups of context for any threads that are alive. Caution should be+-- taken for consumers of this module to not retain ThreadId references+-- indefinitely, as that could delay cleanup of thread-local state.+--+-- Thread-local contexts have the following semantics:+--+-- - A value 'attach'ed to a 'ThreadId' will remain alive at least as long+--   as the 'ThreadId'. +-- - A value may be detached from a 'ThreadId' via 'detach' by the+--   library consumer without detriment.+-- - No guarantees are made about when a value will be garbage-collected+--   once all references to 'ThreadId' have been dropped. However, this simply+--   means in practice that any unused contexts will cleaned up upon the next+--   garbage collection and may not be actively freed when the program exits.+--+-- Note that this implementation of context sharing is+-- mildly expensive for the garbage collector, hard to reason about without deep+-- knowledge of the code you are instrumenting, and has limited guarantees of behavior +-- across GHC versions due to internals usage.+module Control.Concurrent.Thread.Storage +  ( +    -- * Create a 'ThreadStorageMap'+    ThreadStorageMap+  , newThreadStorageMap+    -- * Retrieve values from a 'ThreadStorageMap'+  , lookup+  , lookupOnThread+    -- * Associate values with a thread in a 'ThreadStorageMap'+  , attach+  , attachOnThread+    -- * Remove values from a thread in a 'ThreadStorageMap'+  , detach+  , detachFromThread+    -- * Update values for a thread in a 'ThreadStorageMap'+  , adjust+  , adjustOnThread+    -- * Monitoring utilities+  , storedItems+  ) where++import Control.Concurrent+import Control.Concurrent.Thread.Finalizers+import Control.Monad ( void )+import Control.Monad.IO.Class+import GHC.IO (IO(..))+import GHC.Int+import GHC.Conc.Sync ( ThreadId(..) )+import GHC.Prim+import qualified Data.IntMap.Lazy as I+import Foreign.C.Types+import Prelude hiding (lookup)++foreign import ccall unsafe "rts_getThreadId" c_getThreadId :: ThreadId# -> CInt++numStripes :: Int+numStripes = 32++getThreadId :: ThreadId -> Int+getThreadId (ThreadId tid#) = fromIntegral (c_getThreadId tid#)++threadHash :: Int -> Int+threadHash = (`mod` numStripes)++readStripe :: ThreadStorageMap a -> ThreadId -> IO (I.IntMap a)+readStripe (ThreadStorageMap arr#) t = IO $ \s -> readArray# arr# tid# s+  where+    (I# tid#) = threadHash $ getThreadId t++atomicModifyStripe :: ThreadStorageMap a -> Int -> (I.IntMap a -> (I.IntMap a, b)) -> IO b+atomicModifyStripe (ThreadStorageMap arr#) tid f = IO $ \s -> go s+  where+    (I# stripe#) = threadHash tid+    go s = case readArray# arr# stripe# s of+      (# s1, intMap #) -> +        let (updatedIntMap, result) = f intMap +        in case casArray# arr# stripe# intMap updatedIntMap s1 of+             (# s2, outcome, old #) -> case outcome of+               0# -> (# s2, result #)+               1# -> go s2+               _ -> error "Got impossible result in atomicModifyStripe"+          +-- | A storage mechanism for values of a type. This structure retains items+-- on per-(green)thread basis, which can be useful in rare cases.+data ThreadStorageMap a = ThreadStorageMap (MutableArray# RealWorld (I.IntMap a))++-- | Create a new thread storage map. The map is striped by thread+-- into 32 sections in order to reduce contention.+newThreadStorageMap +  :: MonadIO m => m (ThreadStorageMap a)+newThreadStorageMap = liftIO $ IO $ \s -> case newArray# numStripes# mempty s of+  (# s1, ma #) -> (# s1, ThreadStorageMap ma #)+  where+    (I# numStripes#) = numStripes++-- | Retrieve a value if it exists for the current thread+lookup :: MonadIO m => ThreadStorageMap a -> m (Maybe a)+lookup tsm = liftIO $ do+  tid <- myThreadId+  lookupOnThread tsm tid++-- | Retrieve a value if it exists for the specified thread+lookupOnThread :: MonadIO m => ThreadStorageMap a -> ThreadId -> m (Maybe a)+lookupOnThread tsm tid = liftIO $ do+  let threadAsInt = getThreadId tid+  m <- readStripe tsm tid+  pure $ I.lookup threadAsInt m++-- | Associate the provided value with the current thread+attach :: MonadIO m => ThreadStorageMap a -> a -> m ()+attach tsm x = liftIO $ do+  tid <- myThreadId+  attachOnThread tsm tid x++-- | Associate the provided value with the specified thread+attachOnThread :: MonadIO m => ThreadStorageMap a -> ThreadId -> a -> m ()+attachOnThread tsm tid ctxt = liftIO $ do+  let threadAsInt = getThreadId tid+  addThreadFinalizer tid $ cleanUp tsm threadAsInt+  atomicModifyStripe tsm threadAsInt $ \m -> (I.insert threadAsInt ctxt m, ())++-- | Disassociate the associated value from the current thread, returning it if it exists.+detach :: MonadIO m => ThreadStorageMap a -> m (Maybe a)+detach tsm = liftIO $ do+  tid <- myThreadId+  detachFromThread tsm tid++-- | Disassociate the associated value from the specified thread, returning it if it exists.+detachFromThread :: MonadIO m => ThreadStorageMap a -> ThreadId -> m (Maybe a)+detachFromThread tsm tid = liftIO $ do+  let threadAsInt = getThreadId tid+  atomicModifyStripe tsm threadAsInt $ \m -> (I.delete threadAsInt m, I.lookup threadAsInt m)++-- | Update the associated value for the current thread if it is attached.+adjust :: MonadIO m => ThreadStorageMap a -> (a -> a) -> m ()+adjust tsm f = liftIO $ do+  tid <- myThreadId+  adjustOnThread tsm tid f++-- | Update the associated value for the specified thread if it is attached.+adjustOnThread :: MonadIO m => ThreadStorageMap a -> ThreadId -> (a -> a) -> m ()+adjustOnThread tsm tid f = liftIO $ do+  let threadAsInt = getThreadId tid +  atomicModifyStripe tsm threadAsInt $ \m -> (I.adjust f threadAsInt m, ())++-- Remove this context for thread from the map on finalization+cleanUp :: ThreadStorageMap a -> Int -> IO ()+cleanUp tsm tid = atomicModifyStripe tsm tid $ \m -> +  (I.delete tid m, ())++-- | List thread ids with live entries in the 'ThreadStorageMap'.+-- +-- This is useful for monitoring purposes to verify that there+-- are no memory leaks retaining threads and thus preventing+-- items from being freed from a 'ThreadStorageMap' +storedItems :: ThreadStorageMap a -> IO [Int]+storedItems tsm = do+  stripes <- mapM (stripeByIndex tsm) [0..(numStripes - 1)]+  pure $ concatMap I.keys stripes++stripeByIndex :: ThreadStorageMap a -> Int -> IO (I.IntMap a)+stripeByIndex (ThreadStorageMap arr#) (I# i#) = IO $ \s -> readArray# arr# i# s

+ test/Spec.hs view

@@ -0,0 +1,25 @@+{-# LANGUAGE NumericUnderscores #-}+import System.Mem+import Control.Concurrent+import Control.Concurrent.MVar+import Control.Concurrent.Thread.Storage+import Control.Monad++main :: IO ()+main = do+  mv <- newEmptyMVar+  tsm <- newThreadStorageMap+  replicateM_ 20 $ do+    forkIO $ do+      myThreadId >>= print+      attach tsm ()+      readMVar mv+  threadDelay 2_000_000+  print =<< storedItems tsm+  putMVar mv ()+  threadDelay 2_000_000+  performGC+  print =<< storedItems tsm++  +

+ thread-utils-context.cabal view

@@ -0,0 +1,56 @@+cabal-version: 1.12++-- This file has been generated from package.yaml by hpack version 0.34.4.+--+-- see: https://github.com/sol/hpack++name:           thread-utils-context+version:        0.1.0.0+synopsis:       Garbage-collected thread local storage+description:    Please see the README on GitHub at <https://github.com/iand675/thread-utils-context#readme>+category:       Concurrency+homepage:       https://github.com/iand675/thread-utils#readme+bug-reports:    https://github.com/iand675/thread-utils/issues+author:         Ian Duncan+maintainer:     ian@iankduncan.com+copyright:      2021 Ian Duncan+license:        BSD3+license-file:   LICENSE+build-type:     Simple+extra-source-files:+    README.md+    ChangeLog.md++source-repository head+  type: git+  location: https://github.com/iand675/thread-utils++library+  exposed-modules:+      Control.Concurrent.Thread.Storage+  other-modules:+      Paths_thread_utils_context+  hs-source-dirs:+      src+  build-depends:+      base >=4.7 && <5+    , containers+    , ghc-prim+    , thread-utils-finalizers+  default-language: Haskell2010++test-suite thread-utils-context-test+  type: exitcode-stdio-1.0+  main-is: Spec.hs+  other-modules:+      Paths_thread_utils_context+  hs-source-dirs:+      test+  ghc-options: -threaded -rtsopts -with-rtsopts=-N+  build-depends:+      base >=4.7 && <5+    , containers+    , ghc-prim+    , thread-utils-context+    , thread-utils-finalizers+  default-language: Haskell2010