Context

Introduction

This module provides an opaque Store for thread-indexed storage around arbitrary context values. The interface supports nesting context values per thread, and at any point, the calling thread may ask for its current context.

Note that threads in Haskell have no explicit parent-child relationship. So if you register a context in a Store produced by withEmptyStore, spin up a separate thread, and from that thread you ask for a context, that thread will not have a context in the Store. Use Context.Concurrent as a drop-in replacement for Control.Concurrent to have the library handle context propagation from one thread to another automatically. Otherwise, you must explicitly register contexts from each thread when using a Store produced by withEmptyStore.

If you have a default context that is always applicable to all threads, you may wish to use withNonEmptyStore. All threads may access this default context (without leveraging Context.Concurrent or explicitly registering context for the threads) when using a Store produced by withNonEmptyStore.

Regardless of how you initialize your Store, every thread is free to nest its own specific context values.

This module is designed to be imported qualified:

import qualified Context

Storage

data Store ctx

Opaque type that manages thread-indexed storage of context values.

Since: 0.1.0.0

withNonEmptyStore :: ctx -> (Store ctx -> IO a) -> IO a

Provides a new, non-empty Store that uses the specified context value as a default when the calling thread has no registered context. mine, mines, and adjust are guaranteed to never throw NotFoundException when applied to a non-empty Store.

Since: 0.1.0.0

withEmptyStore :: (Store ctx -> IO a) -> IO a

Provides a new, empty Store. mine, mines, and adjust will throw NotFoundException when the calling thread has no registered context. Useful when the Store will contain context values that are always thread-specific.

Since: 0.1.0.0

Operations

Registering context

use :: Store ctx -> ctx -> IO a -> IO a

Register a context in the specified Store on behalf of the calling thread, for the duration of the specified action.

Since: 0.1.0.0

adjust :: Store ctx -> (ctx -> ctx) -> IO a -> IO a

Adjust the calling thread's context in the specified Store for the duration of the specified action. Throws a NotFoundException when the calling thread has no registered context.

Since: 0.1.0.0

Asking for context

mine :: Store ctx -> IO ctx

Provide the calling thread its current context from the specified Store. Throws a NotFoundException when the calling thread has no registered context.

Since: 0.1.0.0

mines :: Store ctx -> (ctx -> a) -> IO a

Provide the calling thread a selection from its current context in the specified Store. Throws a NotFoundException when the calling thread has no registered context.

Since: 0.1.0.0

mineMay :: Store ctx -> IO (Maybe ctx)

Provide the calling thread its current context from the specified Store, if present.

Since: 0.1.0.0

minesMay :: Store ctx -> (ctx -> a) -> IO (Maybe a)

Provide the calling thread a selection from its current context in the specified Store, if present.

Since: 0.1.0.0

Exceptions

data NotFoundException

An exception which may be thrown via mine, mines, and adjust when the calling thread does not have a registered context.

Since: 0.1.0.0

Constructors

NotFoundException

Fields

• threadId :: ThreadId

Instances

Eq NotFoundException

Defined in Context

Methods

(==) :: NotFoundException -> NotFoundException -> Bool

(/=) :: NotFoundException -> NotFoundException -> Bool

Show NotFoundException

Defined in Context

Methods

showsPrec :: Int -> NotFoundException -> ShowS

show :: NotFoundException -> String

showList :: [NotFoundException] -> ShowS

Generic NotFoundException

Defined in Context

Associated Types

type Rep NotFoundException :: Type -> Type

Methods

from :: NotFoundException -> Rep NotFoundException x

to :: Rep NotFoundException x -> NotFoundException

Exception NotFoundException

Defined in Context

Methods

toException :: NotFoundException -> SomeException

fromException :: SomeException -> Maybe NotFoundException

displayException :: NotFoundException -> String

type Rep NotFoundException

Defined in Context

type Rep NotFoundException = D1 (MetaData "NotFoundException" "Context" "context-0.1.0.0-3hddOWlDNv2wEyCRw8vfF" False) (C1 (MetaCons "NotFoundException" PrefixI True) (S1 (MetaSel (Just "threadId") NoSourceUnpackedness NoSourceStrictness DecidedStrict) (Rec0 ThreadId)))

Concurrency

module Context.Concurrent

Lower-level storage

module Context.Storage