Data.Primitive.Unlifted.Weak.Primops

Primops for weak references from (lifted or unlifted) values to unlifted values. Several of these use a slightly different interface than the underlying GHC primops. I have a GHC proposal in progress (https:/github.comghc-proposalsghc-proposalspull/367) to make GHC match this interface. Note that the GHC primops work just fine with unlifted types as keys, so we only need to fake our own to use unlifted types as values.

Documentation

data UnliftedWeak# (a :: TYPE 'UnliftedRep)

A weak pointer from a key (which may be lifted or unlifted) to an unlifted value.

mkWeakFromUnliftedToUnlifted# :: forall (k :: TYPE 'UnliftedRep) (v :: TYPE 'UnliftedRep) c. k -> v -> (State# RealWorld -> (# State# RealWorld, c #)) -> State# RealWorld -> (# State# RealWorld, UnliftedWeak# v #)

mkWeakFromUnliftedToUnlifted# k v finalizer s creates a weak reference from an unlifted value k to some unlifted value v. If k is still alive then v can be retrieved using deRefUnliftedWeak#.

mkWeakFromUnliftedToUnliftedNoFinalizer# :: forall (k :: TYPE 'UnliftedRep) (v :: TYPE 'UnliftedRep). k -> v -> State# RealWorld -> (# State# RealWorld, UnliftedWeak# v #)

The same as mkWeakFromUnliftedToUnlifted# but without a finalizer.

mkWeakToUnlifted# :: forall k (v :: TYPE 'UnliftedRep) c. k -> v -> (State# RealWorld -> (# State# RealWorld, c #)) -> State# RealWorld -> (# State# RealWorld, UnliftedWeak# v #)

mkWeakToUnlifted# k v finalizer s creates a weak reference from a lifted value k to some unlifted value v. If k is still alive then v can be retrieved using deRefUnliftedWeak#.

mkWeakToUnliftedNoFinalizer# :: forall k (v :: TYPE 'UnliftedRep). k -> v -> State# RealWorld -> (# State# RealWorld, UnliftedWeak# v #)

The same as mkWeakToUnlifted# but without a finalizer.

addCFinalizerToUnliftedWeak1# :: Addr# -> Addr# -> UnliftedWeak# b -> State# RealWorld -> (# State# RealWorld, Int# #)

addCFinalizerToUnliftedWeak1# fptr ptr w attaches a C function pointer fptr to a weak pointer w as a finalizer. ptr is an argument to be passed to fptr. addCFinalizerToWeak1# returns 1# on success, or 0# if w is already dead.

addCFinalizerToUnliftedWeak2# :: Addr# -> Addr# -> Addr# -> UnliftedWeak# b -> State# RealWorld -> (# State# RealWorld, Int# #)

addCFinalizerToUnliftedWeak2# fptr eptr ptr w attaches a C function pointer fptr to a weak pointer w as a finalizer. eptr and ptr are arguments which will be passed to fptr in order. addCFinalizerToWeak2# returns 1# on success, or 0# if w is already dead.

deRefUnliftedWeak# :: UnliftedWeak# v -> State# RealWorld -> (# State# RealWorld, (# (# #) | v #) #)

Dereference an UnliftedWeak#. If the pointer is already dead, returns (). Otherwise returns (), where v is the target of the weak pointer.

finalizeUnliftedWeak# :: UnliftedWeak# v -> State# RealWorld -> (# State# RealWorld, (# (# #) | State# RealWorld -> (# State# RealWorld, b #) #) #)

finalizeUnliftedWeak# attempts to finalize an UnliftedWeak#. If the weak pointer is already dead, or it has no Haskell finalizer, it returns (). Otherwise, it returns (), where f is the Haskell finalization action. The return value b from the finalizer should be ignored. finalizeUnliftedWeak# breaks the connection the UnliftedWeak# has maintained between key and value and runs any C finalizers. After finalization, deRefUnliftedWeak# will return ().