| Copyright | (c) Ian Duncan 2021 |
|---|---|
| License | BSD-3 |
| Maintainer | Ian Duncan |
| Stability | experimental |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
OpenTelemetry.Context.ThreadLocal
Description
Thread-local contexts may be attached as implicit state at a per-Haskell-thread level.
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
attached to aThreadIdwill remain alive at least as long as theThreadId. - A value may be detached from a
ThreadIdviadetachby the library consumer without detriment. - No guarantees are made about when a value will be garbage-collected
once all references to
ThreadIdhave 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.
Synopsis
- getContext :: MonadIO m => m Context
- lookupContext :: MonadIO m => m (Maybe Context)
- attachContext :: MonadIO m => Context -> m (Maybe Context)
- detachContext :: MonadIO m => m (Maybe Context)
- adjustContext :: MonadIO m => (Context -> Context) -> m ()
- lookupContextOnThread :: MonadIO m => ThreadId -> m (Maybe Context)
- attachContextOnThread :: MonadIO m => ThreadId -> Context -> m (Maybe Context)
- detachContextFromThread :: MonadIO m => ThreadId -> m (Maybe Context)
- adjustContextOnThread :: MonadIO m => ThreadId -> (Context -> Context) -> m ()
- threadContextMap :: ThreadContextMap
Thread-local context
getContext :: MonadIO m => m Context Source #
Retrieve a stored Context for the current thread, or an empty context if none exists.
Warning: this can easily cause disconnected traces if libraries don't explicitly set the context on forked threads.
Since: 0.0.1.0
lookupContext :: MonadIO m => m (Maybe Context) Source #
Retrieve a stored Context for the current thread, if it exists.
Since: 0.0.1.0
attachContext :: MonadIO m => Context -> m (Maybe Context) Source #
Store a given Context for the current thread, returning any context previously stored.
Since: 0.0.1.0
detachContext :: MonadIO m => m (Maybe Context) Source #
Remove a stored Context for the current thread, returning any context previously stored.
The detach functions don't generally need to be called manually, because finalizers will automatically clean up contexts when a thread has completed and been garbage collected. If you are replacing a context on a long-lived thread by detaching and attaching, use `adjustContext (const newContext)` instead to avoid registering additional finalizer functions to be called on thread exit.
Since: 0.0.1.0
adjustContext :: MonadIO m => (Context -> Context) -> m () Source #
Alter the context on the current thread using the provided function.
If there is not a context associated with the current thread, the function will be applied to an empty context and the result will be stored
Since: 0.0.1.0
Generalized thread-local context functions
detachContextFromThread :: MonadIO m => ThreadId -> m (Maybe Context) Source #
Remove a stored Context for the provided ThreadId, returning any context previously stored.
The detach functions don't generally need to be called manually, because finalizers will automatically clean up contexts when a thread has completed and been garbage collected. If you are replacing a context on a long-lived thread by detaching and attaching, use `adjustContext (const newContext)` instead to avoid registering additional finalizer functions to be called on thread exit.
Since: 0.0.1.0
adjustContextOnThread :: MonadIO m => ThreadId -> (Context -> Context) -> m () Source #
Alter the context
If there is not a context associated with the provided thread, the function will be applied to an empty context and the result will be stored
Since: 0.0.1.0
Debugging tools
threadContextMap :: ThreadContextMap Source #
This is a global variable that is used to store the thread-local context map. It is not intended to be used directly for production purposes, but is exposed for debugging purposes.