Modulekes-agent-crypto-1.2.0.0Haskell2010

Cardano.KESAgent.Util.RefCounting

References with a counter-based lifecycle, similar to reference-counted shared pointers. This is useful to implement shared access to scarce resources that require timely destruction (i.e., we cannot rely on GC to run finalizers).

6 types
12 values

Packagekes-agent-crypto-1.2.0.0
Exports18
LanguageHaskell2010
LicenceApache-2.0
SourceRefCounting.hs

datadata CRef (m :: Type -> Type) a

A reference-counted value.

typetype CRefCount = Int

Reference count. We use a signed integer so that we can catch cases where a reference is released beyond zero (which shouldn't happen, but we want to be able to detect it when it does).

datadata CRefEvent

CRef lifecycle events.

Constructors

CRefEvent
- creType :: !CRefEventType
  what happened
- creID :: !CRefID
  which CRef was affected
- creCountBefore :: !CRefCount
  refcount before the event
- creCountAfter :: !CRefCount
  refcount after the event

Instances3Eq, Show, Pretty

Eq CRefEventDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting
Show CRefEventDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting
Pretty CRefEventDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting

datadata CRefEventType

CRef lifecycle event types.

CRefCreate CRefAcquire CRefRelease

Instances2Eq, Show

Eq CRefEventTypeDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting
Show CRefEventTypeDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting

typetype CRefID = Word32

Unique identifier for a CRef. Mainly used for debugging.

datadata ReferenceCountUnderflow

Reference underflow exception: this will be thrown when a reference count is released beyond zero (i.e., becomes negative). This is generally a bug, caused by user code releasing a reference that it hasn't acquired.

ReferenceCountUnderflow

Instances3Eq, Show, Exception

Eq ReferenceCountUnderflowDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting
Show ReferenceCountUnderflowDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting
Exception ReferenceCountUnderflowDefined in kes-agent-crypto-1.2.0.0 · Cardano.KESAgent.Util.RefCounting

valueacquireCRef :: (MonadSTM m, MonadThrow m) => CRef m a -> m a

Increment the CRef counter such that it will not be finalized until we releaseCRef it again.

valuegetCRefCount :: MonadSTM m => CRef m a -> m Int

Gets the current reference count for the CRef.

valuenewCRef

:: (MonadST m, MonadSTM m, MonadThrow m)
=> a -> m ()
-> a
-> m (CRef m a)

Create a fresh CRef. Its counter will be initialized to 1; the caller is responsible for calling releaseCRef to release it. newCRef f i creates a CRef with an initial value of i, and a finalizer f.

valuenewCRefWith

:: (MonadST m, MonadSTM m, MonadThrow m)
=> Tracer m CRefEvent
-> a -> m ()
-> a
-> m (CRef m a)

Create a fresh CRef attaching a custom tracer (see newCRef).

valuereadCRef :: (MonadSTM m, MonadThrow m) => CRef m a -> m a

Read a CRef without acquiring it. The caller is responsible for making sure the CRef has been acquired appropriately for the duration of the call, and while using the wrapped resource. It is generally preferable to use withCRefValue instead.

valuereleaseCRef :: (MonadSTM m, MonadThrow m) => CRef m a -> m ()

Release a CRef by decrementing its counter. When the counter reaches zero, the resource is finalized. Releasing a CRef more often than it has been acquired is an error, and will (eventually) throwIO ReferenceCountUnderflow exceptions.

valuewithCRef

:: (MonadSTM m, MonadThrow m)
=> CRef m a
-> CRef m a -> m b
-> m b

Operate on a CRef. The CRef is guaranteed to not finalize for the duration of the wrapped function call.

valuewithCRefValue :: (MonadSTM m, MonadThrow m) => CRef m a -> (a -> m b) -> m b

Operate on a CRef. The CRef is guaranteed to not finalize for the duration of the wrapped function call.

valuewithNewCRef

:: (MonadST m, MonadSTM m, MonadThrow m)
=> a -> m ()
-> a
-> CRef m a -> m b
-> m b

Create a fresh CRef and operate on it immediately. See newCRef.

valuewithNewCRefValue

:: (MonadST m, MonadSTM m, MonadThrow m)
=> a -> m ()
-> a
-> a -> m b
-> m b

Create a fresh CRef and operate on its value immediately. See newCRef.

valuewithNewCRefValueWith

:: (MonadST m, MonadSTM m, MonadThrow m)
=> Tracer m CRefEvent
-> a -> m ()
-> a
-> a -> m b
-> m b

Create a fresh CRef with a tracer and operate on its value immediately. See newCRefWith.

valuewithNewCRefWith

:: (MonadST m, MonadSTM m, MonadThrow m)
=> Tracer m CRefEvent
-> a -> m ()
-> a
-> CRef m a -> m b
-> m b

Create a fresh CRef with a tracer and operate on it immediately. See newCRefWith.