Safe Haskell	None
Language	Haskell2010

Bluefin.CloneableHandle

Contents

CloneableHandle
GHC.Generics re-exports

Description

Bluefin.CloneableHandle defines the CloneableHandle class, whose purpose is to support withEffToIOCloneHandle.

Synopsis

withEffToIOCloneHandle :: forall (e1 :: Effects) (es :: Effects) h a. (e1 :> es, CloneableHandle h) => IOE e1 -> h es -> ((forall r. (forall (e :: Effects). IOE e -> h e -> Eff e r) -> IO r) -> IO a) -> Eff es a
class Handle h => CloneableHandle (h :: Effects -> Type)
newtype GenericCloneableHandle (h :: k -> Type) (e :: k) = MkGenericCloneableHandle (h e)
class Handle h => GCloneableHandle (h :: Effects -> Type)
class Generic1 (f :: k -> Type)

Documentation

withEffToIOCloneHandle is an IO unlifting function that clones its handle each time it runs Eff in IO. This is convenient when the unlifting function is being used to fork threads, since Bluefin state is not threadsafe. Be careful when you use it, because it can be used to throw away the effect tag on a Bluefin Eff action due to this part of its type (here throwing away e):

(forall e. IOE e -> h e -> Eff e r) -> IO r

It is only safely used when you do not allow any effects to escape their scope, so we suggest that you use it sparingly to define reusable combinators which themselves are safe. For example, here is how you could write an equivalent of async's race primitive:

bluefinRace ::
  (CloneableHandle h, e1 :> es) =>
  IOE e1 ->
  h es ->
  (forall e. IOE e -> h e -> Eff e r) ->
  (forall e. IOE e -> h e -> Eff e r) ->
  Eff es r
bluefinRace io h m1 m2 = withEffToIOCloneHandle io h $ \runInIO -> do
 either id id
   <$> Control.Concurrent.Async.race
     (runInIO $ \io' h' -> m1 io' h')
     (runInIO $ \io' h' -> m2 io' h')

Then you can safely use it to race Bluefin Eff actions:

example :: IO ()
example = runEff_ $ \io -> evalState 0 $ \st -> do
  r <- try $ \ex -> do
    bluefinRace
      io
      (MkMyHandle (mapHandle ex) (mapHandle st))
      ( \_ (MkMyHandle ex' st') -> do
          modify st' (subtract 2000)
          throw ex' "Aborting from branch 1"
      )
      ( \_ (MkMyHandle _ st') -> do
          modify st' (+ 3000)
          pure (2 :: Int)
      )

  s <- get st
  effIO io (print r)
  effIO io (putStrLn ("State started at 0 and was cloned. Now: " <> show s))

You can see from the output that the actions were raced as expected, and the State was cloned so that changes to it in the branches of race did not affect the original State.

-- Run one time (the first thread was faster)
ghci> example
Right 2
State started at 0 and was cloned. Now: 0
-- Run another time (the second thread was faster)
ghci> example
Left "Aborting from branch 1"
State started at 0 and was cloned. Now: 0

Note that withEffToIOCloneHandle only allows access to one external Handle within it, so if you have several you'd like to use you'll have to define a new handle that bundles them together.

withEffToIOCloneHandle #

Arguments

:: forall (e1 :: Effects) (es :: Effects) h a. (e1 :> es, CloneableHandle h)
=> IOE e1
-> h es	Handle accessible in the continuation
-> ((forall r. (forall (e :: Effects). IOE e -> h e -> Eff e r) -> IO r) -> IO a)	Continuation with the unlifting function in scope.
-> Eff es a

`CloneableHandle`

class Handle h => CloneableHandle (h :: Effects -> Type) #

You can define a CloneableHandle instance for your Handle as long as it is a product type of CloneableHandles. To define the instance, use DerivingVia and GenericCloneableHandle. For example:

data MyHandle e = MkMyHandle (Exception String e) (State Int e)
  deriving (Generic, Generic1)
  deriving (Handle) via OneWayCoercibleHandle MyHandle
  deriving (CloneableHandle) via GenericCloneableHandle MyHandle

instance (e :> es) => OneWayCoercible (MyHandle e) (MyHandle es) where
  oneWayCoercibleImpl = gOneWayCoercible

Minimal complete definition

cloneableHandleImpl

Instances

Instances details

CloneableHandle IOE
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD IOE #
CloneableHandle (Exception a)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (Exception a) #
CloneableHandle h => CloneableHandle (HandleReader h)	Cloning a `HandleReader` copies its contents to a new `HandleReader`. Changes to one will not effect the other.
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (HandleReader h) #
CloneableHandle (Reader r)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (Reader r) #
CloneableHandle (State s)	Cloning a `State` copies its contents to a new `State`. Changes to one will not effect the other.
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (State s) #
(TypeError ('Text "Writer cannot be cloned. Perhaps you want an STM channel?") :: Constraint) => CloneableHandle (Writer w)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (Writer w) #
(TypeError ('Text "Coroutine cannot be cloned. Perhaps you want an STM channel?") :: Constraint) => CloneableHandle (Coroutine a b)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (Coroutine a b) #
(Handle h, Generic1 h, GCloneableHandle (Rep1 h)) => CloneableHandle (GenericCloneableHandle h)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (GenericCloneableHandle h) #

newtype GenericCloneableHandle (h :: k -> Type) (e :: k) #

You can use DerivingVia with GenericCloneableHandle to derive a CloneableHandle instance for your type, as long as it is a product type of CloneableHandles.

Constructors

MkGenericCloneableHandle (h e)

Instances

Instances details

Handle h => Handle (GenericCloneableHandle h)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods handleImpl :: HandleD (GenericCloneableHandle h) # mapHandle :: forall (e :: Effects) (es :: Effects). e :> es => GenericCloneableHandle h e -> GenericCloneableHandle h es #
(Handle h, Generic1 h, GCloneableHandle (Rep1 h)) => CloneableHandle (GenericCloneableHandle h)
Instance details Defined in Bluefin.Internal.CloneableHandle Methods cloneableHandleImpl :: CloneableHandleD (GenericCloneableHandle h) #

class Handle h => GCloneableHandle (h :: Effects -> Type) #

Generic implementation detail of GenericCloneableHandle. Bluefin users should never need to use this directly.

Minimal complete definition

gCloneableHandleImpl

Instances

Instances details

CloneableHandle h => GCloneableHandle (Rec1 h)	A cloneable handle is generically cloneable
Instance details Defined in Bluefin.Internal.CloneableHandle Methods gCloneableHandleImpl :: CloneableHandleD (Rec1 h) #
(GCloneableHandle h1, GCloneableHandle h2) => GCloneableHandle (h1 :*: h2)	A pair of cloneable handles is generically cloneable
Instance details Defined in Bluefin.Internal.CloneableHandle Methods gCloneableHandleImpl :: CloneableHandleD (h1 :*: h2) #
GCloneableHandle h => GCloneableHandle (M1 i t h)	An annotated cloneable handle is generically cloneable
Instance details Defined in Bluefin.Internal.CloneableHandle Methods gCloneableHandleImpl :: CloneableHandleD (M1 i t h) #

`GHC.Generics` re-exports

class Generic1 (f :: k -> Type) #

Representable types of kind * -> * (or kind k -> *, when PolyKinds is enabled). This class is derivable in GHC with the DeriveGeneric flag on.

A Generic1 instance must satisfy the following laws:

from1 . to1 ≡ id
to1 . from1 ≡ id

Minimal complete definition

from1, to1

Instances

Instances details

Generic1 Down

Instance details

Documentation

CloneableHandle

Instances

Instances

Instances

GHC.Generics re-exports

Instances

`CloneableHandle`

`GHC.Generics` re-exports