-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Several options for thread-local-storage (TLS) in Haskell. -- -- Thread-local storage, or TLS, is an important ingredient in many -- algorithms and data structures. -- -- The GHC compiler does not provide a built-in notion of TLS either at -- the IO-thread or OS thread level. This package provides a few -- different implementations of a simple TLS API. -- -- All exported public modules provide exactly the same interface with -- different implementations. Run the included criterion benchmark suite -- to ascertain which performs the best on your platform. -- -- Example criterion benchmark data can be found here (from an Intel -- Ivy-Bridge i7-3770 desktop): -- http://www.cs.indiana.edu/~rrnewton/datasets/xmen_tls_report.html @package thread-local-storage @version 0.2 -- | This is the simplest implementation of thread-local storage using -- GHC's built-in ThreadId capabilities. -- -- While the interface below is designed to match the other -- implementations of TLS in this package, the GHC implementation can -- generaly be relied upon to keep a stable copy of the TLS variable for -- each ThreadId that calls getTLS. This may change in the -- future, however! module Data.TLS.GHC -- | A thread-local variable of type a. data TLS a -- | Make a new per-thread variable. This guarantees that no two threads -- that execute getTLS simultaneosly will receive the same copy of -- the value. Generally, to meet this guarantee there must be AT LEAST -- one copy of the TLS variable for each distinct OS thread that calls -- getAll. But this is a lower bound, and there may be *more*. -- In particular, there could be one per Haskell IO thread rather than -- per OS thread. -- -- Thread safe. mkTLS :: IO a -> IO (TLS a) -- | Fetch this thread's copy of the TLS variable. Note that all values -- returned by this function may be immune to garbage collected until -- freeTLS is called. -- -- Thread safe. getTLS :: TLS a -> IO a -- | After a TLS-based computation is complete, iterate through all the -- copies of the TLS variable which were used by all threads. -- -- NOT thread safe. allTLS :: TLS a -> IO [a] -- | Like allTLS, but apply a computation directly rather than -- building a list. forEachTLS_ :: TLS a -> (a -> IO ()) -> IO () -- | Release all copies of the TLS variable, across all threads. This does -- not guarantee the storage will be freed immediately, but it guarantees -- that the storage can be reclaimed in the future. -- -- The TLS value is still usable after this call, but any future calls to -- getTLS must initialize new state. -- -- Not thread safe. freeAllTLS :: TLS a -> IO () -- | An alias for freeAllTLS. -- | Deprecated: Replaced by freeAllTLS freeTLS :: TLS a -> IO () -- | Like Data.TLS.PThread, but this also exports internal -- functionality not exposed in the public interface. -- -- There are no API guaranteees whatsoever for this module, so use it -- with with caution. module Data.TLS.PThread.Internal -- | Make a new per-thread variable. This guarantees that no two threads -- that execute getTLS simultaneosly will receive the same copy of -- the value. Generally, to meet this guarantee there must be AT LEAST -- one copy of the TLS variable for each distinct OS thread that calls -- getAll. But this is a lower bound, and there may be *more*. -- In particular, there could be one per Haskell IO thread rather than -- per OS thread. -- -- Thread safe. mkTLS :: IO a -> IO (TLS a) -- | Fetches the copy of the TLS variable of the running OS thread. -- -- The returned value is reliable only if the current thread is bound. -- For this reason, this function calls error if the current -- thread is unbound. -- -- Fetch this thread's copy of the TLS variable. Note that all values -- returned by this function may be immune to garbage collected until -- freeTLS is called. -- -- Thread safe. getTLS :: TLS a -> IO a -- | After a TLS-based computation is complete, iterate through all the -- copies of the TLS variable which were used by all threads. -- -- NOT thread safe. allTLS :: TLS a -> IO [a] -- | Like allTLS, but apply a computation directly rather than -- building a list. forEachTLS_ :: TLS a -> (a -> IO ()) -> IO () -- | An alias for freeAllTLS. -- | Deprecated: Replaced by freeAllTLS freeTLS :: TLS a -> IO () -- | Release all copies of the TLS variable, across all threads. This does -- not guarantee the storage will be freed immediately, but it guarantees -- that the storage can be reclaimed in the future. -- -- The TLS value is still usable after this call, but any future calls to -- getTLS must initialize new state. -- -- Not thread safe. freeAllTLS :: TLS a -> IO () type Key = Word get_pthread_key_size :: Int pthread_key_create :: Ptr Key -> Ptr () -> IO Int easy_make_pthread_key :: IO Key pthread_getspecific :: Key -> IO (StablePtr a) pthread_setspecific :: Key -> StablePtr a -> IO Int pthread_key_delete :: Key -> IO Int check_error :: () setspecific :: Key -> StablePtr a -> IO () delete :: Key -> IO () -- | A thread-local variable of type a. data TLS a TLS :: {-# UNPACK #-} !Key -> !(IO a) -> {-# UNPACK #-} !(IORef [StablePtr a]) -> TLS a [key] :: TLS a -> {-# UNPACK #-} !Key [mknew] :: TLS a -> !(IO a) [allCopies] :: TLS a -> {-# UNPACK #-} !(IORef [StablePtr a]) -- | An implementation of TLS using the standard, Posix -- pthread_create_key routine. -- -- Note that because this implementation uses Posix threads, it does NOT -- care about Haskell IO threads. This module is generally used to avoid -- problems with data structures or other APIs that are not thread safe. -- That is, pthread-based TLS is sufficient to disallow simultaneous -- access, irrespective of where IO threads migrate to. module Data.TLS.PThread -- | A thread-local variable of type a. data TLS a -- | Make a new per-thread variable. This guarantees that no two threads -- that execute getTLS simultaneosly will receive the same copy of -- the value. Generally, to meet this guarantee there must be AT LEAST -- one copy of the TLS variable for each distinct OS thread that calls -- getAll. But this is a lower bound, and there may be *more*. -- In particular, there could be one per Haskell IO thread rather than -- per OS thread. -- -- Thread safe. mkTLS :: IO a -> IO (TLS a) -- | Fetches the copy of the TLS variable of the running OS thread. -- -- The returned value is reliable only if the current thread is bound. -- For this reason, this function calls error if the current -- thread is unbound. -- -- Fetch this thread's copy of the TLS variable. Note that all values -- returned by this function may be immune to garbage collected until -- freeTLS is called. -- -- Thread safe. getTLS :: TLS a -> IO a -- | After a TLS-based computation is complete, iterate through all the -- copies of the TLS variable which were used by all threads. -- -- NOT thread safe. allTLS :: TLS a -> IO [a] -- | Like allTLS, but apply a computation directly rather than -- building a list. forEachTLS_ :: TLS a -> (a -> IO ()) -> IO () -- | Release all copies of the TLS variable, across all threads. This does -- not guarantee the storage will be freed immediately, but it guarantees -- that the storage can be reclaimed in the future. -- -- The TLS value is still usable after this call, but any future calls to -- getTLS must initialize new state. -- -- Not thread safe. freeAllTLS :: TLS a -> IO () -- | An alias for freeAllTLS. -- | Deprecated: Replaced by freeAllTLS freeTLS :: TLS a -> IO ()