-- 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):
--   <a>http://www.cs.indiana.edu/~rrnewton/datasets/xmen_tls_report.html</a>
@package thread-local-storage
@version 0.1.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 <a>ThreadId</a> that calls <a>getTLS</a>. This may change in the
--   future, however!
module Data.TLS.GHC

-- | A thread-local variable of type <tt>a</tt>.
data TLS a

-- | Make a new per-thread variable. This guarantees that no two threads
--   that execute <a>getTLS</a> 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
--   <tt>getAll</tt>. 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
--   <a>freeTLS</a> 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 <a>allTLS</a>, 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
--   <a>getTLS</a> must initialize new state.
--   
--   Not thread safe.
freeAllTLS :: TLS a -> IO ()

-- | An alias for <a>freeAllTLS</a>.

-- | <i>Deprecated: Replaced by freeAllTLS</i>
freeTLS :: TLS a -> IO ()


-- | Like <a>Data.TLS.PThread</a>, 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 <a>getTLS</a> 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
--   <tt>getAll</tt>. 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
--   <a>freeTLS</a> 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 <a>allTLS</a>, but apply a computation directly rather than
--   building a list.
forEachTLS_ :: TLS a -> (a -> IO ()) -> IO ()

-- | An alias for <a>freeAllTLS</a>.

-- | <i>Deprecated: Replaced by freeAllTLS</i>
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
--   <a>getTLS</a> 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 <tt>a</tt>.
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
--   <tt>pthread_create_key</tt> 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 <tt>a</tt>.
data TLS a

-- | Make a new per-thread variable. This guarantees that no two threads
--   that execute <a>getTLS</a> 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
--   <tt>getAll</tt>. 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
--   <a>freeTLS</a> 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 <a>allTLS</a>, 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
--   <a>getTLS</a> must initialize new state.
--   
--   Not thread safe.
freeAllTLS :: TLS a -> IO ()

-- | An alias for <a>freeAllTLS</a>.

-- | <i>Deprecated: Replaced by freeAllTLS</i>
freeTLS :: TLS a -> IO ()
