Game.GoreAndAsh.Async

The core module contains API for embedding concurrent IO actions (async and sync) into main game loop for Gore&Ash.

The module does not depend on any other core modules, so AsyncT could be placed at any place in monad stack.

The module is NOT pure within first phase (see ModuleStack docs), therefore currently only IO end monad can handler the module.

Example of embedding:

-- Language extensions: DataKinds DeriveGeneric GeneralizedNewtypeDeriving MultiParamTypeClasses TypeFamilies
import Control.DeepSeq
import Control.Monad.Catch
import Control.Monad.Fix 
import Control.Monad.IO.Class
import Data.Typeable 
import GHC.Generics (Generic)

import Game.GoreAndAsh.Core
import Game.GoreAndAsh.Async 

-- | Application monad is monad stack build from given list of modules over base monad (IO or Identity)
type AppStack = ModuleStack [AsyncT ... other modules ... ] IO
newtype AppState = AppState (ModuleState AppStack)
  deriving (Generic)

instance NFData AppState 

-- | Wrapper around type family
newtype AppMonad a = AppMonad (AppStack a)
  deriving (Functor, Applicative, Monad, MonadFix, MonadIO, MonadThrow, MonadCatch, MonadAsync ... other modules monads ... )

instance GameModule AppMonad AppState where 
  type ModuleState AppMonad = AppState
  runModule (AppMonad m) (AppState s) = do 
    (a, s') <- runModule m s 
    return (a, AppState s')
  newModuleState = AppState $ newModuleState
  withModule _ = withModule (Proxy :: Proxy AppStack)
  cleanupModule (AppState s) = cleanupModule s 

-- | Arrow that is build over the monad stack
type AppWire a b = GameWire AppMonad a b

Low-level

data AsyncState s

Internal state of asynchronious core module

s

- state of next module, they are chained until bottom, that is usually an empty data type.

Instances

Generic (AsyncState s)

Associated Types

type Rep (AsyncState s) :: * -> *

Methods

from :: AsyncState s -> Rep (AsyncState s) x

to :: Rep (AsyncState s) x -> AsyncState s

NFData s => NFData (AsyncState s)

Methods

rnf :: AsyncState s -> ()

Monad m => MonadState (AsyncState s) (AsyncT s m)

Methods

get :: AsyncT s m (AsyncState s)

put :: AsyncState s -> AsyncT s m ()

state :: (AsyncState s -> (a, AsyncState s)) -> AsyncT s m a

type Rep (AsyncState s)

type Rep (AsyncState s) = D1 (MetaData "AsyncState" "Game.GoreAndAsh.Async.State" "gore-and-ash-async-1.1.1.0-2OVkZlWWiw2AoycryFpZ3T" False) (C1 (MetaCons "AsyncState" PrefixI True) ((:*:) ((:*:) (S1 (MetaSel (Just Symbol "asyncAValues") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 AsyncValueMap)) (S1 (MetaSel (Just Symbol "asyncScheduled") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 SyncSheduled))) ((:*:) (S1 (MetaSel (Just Symbol "asyncSValues") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 SyncFinished)) ((:*:) (S1 (MetaSel (Just Symbol "asyncNextId") NoSourceUnpackedness SourceStrict DecidedUnpack) (Rec0 Int)) (S1 (MetaSel (Just Symbol "asyncNextState") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 s))))))

data AsyncT s m a

Monad transformer of async core module.

s

- State of next core module in modules chain;

m

- Next monad in modules monad stack;

a

- Type of result value;

How to embed module:

type AppStack = ModuleStack [AsyncT, ... other modules ... ] IO

newtype AppMonad a = AppMonad (AppStack a)
  deriving (Functor, Applicative, Monad, MonadFix, MonadIO, MonadThrow, MonadCatch, MonadAsync)

The module is NOT pure within first phase (see ModuleStack docs), therefore currently only IO end monad can handler the module.

Instances

MonadBase IO m => MonadBase IO (AsyncT s m)

Methods

liftBase :: IO α -> AsyncT s m α

MonadError e m => MonadError e (AsyncT s m)

Methods

throwError :: e -> AsyncT s m a

catchError :: AsyncT s m a -> (e -> AsyncT s m a) -> AsyncT s m a

MonadTrans (AsyncT s)

Methods

lift :: Monad m => m a -> AsyncT s m a

Monad m => MonadState (AsyncState s) (AsyncT s m)

Methods

get :: AsyncT s m (AsyncState s)

put :: AsyncState s -> AsyncT s m ()

state :: (AsyncState s -> (a, AsyncState s)) -> AsyncT s m a

Monad m => Monad (AsyncT s m)

Methods

(>>=) :: AsyncT s m a -> (a -> AsyncT s m b) -> AsyncT s m b

(>>) :: AsyncT s m a -> AsyncT s m b -> AsyncT s m b

return :: a -> AsyncT s m a

fail :: String -> AsyncT s m a

Functor m => Functor (AsyncT s m)

Methods

fmap :: (a -> b) -> AsyncT s m a -> AsyncT s m b

(<$) :: a -> AsyncT s m b -> AsyncT s m a

MonadFix m => MonadFix (AsyncT s m)

Methods

mfix :: (a -> AsyncT s m a) -> AsyncT s m a

Monad m => Applicative (AsyncT s m)

Methods

pure :: a -> AsyncT s m a

(<*>) :: AsyncT s m (a -> b) -> AsyncT s m a -> AsyncT s m b

(*>) :: AsyncT s m a -> AsyncT s m b -> AsyncT s m b

(<*) :: AsyncT s m a -> AsyncT s m b -> AsyncT s m a

MonadIO m => MonadIO (AsyncT s m)

Methods

liftIO :: IO a -> AsyncT s m a

MonadThrow m => MonadThrow (AsyncT s m)

Methods

throwM :: Exception e => e -> AsyncT s m a

MonadMask m => MonadMask (AsyncT s m)

Methods

mask :: ((forall a. AsyncT s m a -> AsyncT s m a) -> AsyncT s m b) -> AsyncT s m b

uninterruptibleMask :: ((forall a. AsyncT s m a -> AsyncT s m a) -> AsyncT s m b) -> AsyncT s m b

MonadCatch m => MonadCatch (AsyncT s m)

Methods

catch :: Exception e => AsyncT s m a -> (e -> AsyncT s m a) -> AsyncT s m a

MonadResource m => MonadResource (AsyncT s m)

Methods

liftResourceT :: ResourceT IO a -> AsyncT s m a

(MonadIO m, MonadThrow m) => MonadAsync (AsyncT s m)

Methods

asyncActionM :: Typeable * a => IO a -> AsyncT s m AsyncId

asyncActionBoundM :: Typeable * a => IO a -> AsyncT s m AsyncId

asyncPollM :: Typeable * a => AsyncId -> AsyncT s m (Maybe (Either SomeException a))

asyncCancelM :: AsyncId -> AsyncT s m ()

asyncSyncActionM :: Typeable * a => IO a -> AsyncT s m SyncId

asyncSyncPollM :: Typeable * a => SyncId -> AsyncT s m (Maybe (Either SomeException a))

asyncSyncCanceM :: SyncId -> AsyncT s m ()

type ModuleState (AsyncT s m)

type ModuleState (AsyncT s m) = AsyncState s

data AsyncId

Id of async value, it is used to poll info about the value

Instances

Eq AsyncId

Methods

(==) :: AsyncId -> AsyncId -> Bool

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

Show AsyncId

Methods

showsPrec :: Int -> AsyncId -> ShowS

show :: AsyncId -> String

showList :: [AsyncId] -> ShowS

Generic AsyncId

Associated Types

type Rep AsyncId :: * -> *

Methods

from :: AsyncId -> Rep AsyncId x

to :: Rep AsyncId x -> AsyncId

NFData AsyncId

Methods

rnf :: AsyncId -> ()

Hashable AsyncId

Methods

hashWithSalt :: Int -> AsyncId -> Int

hash :: AsyncId -> Int

type Rep AsyncId

type Rep AsyncId = D1 (MetaData "AsyncId" "Game.GoreAndAsh.Async.State" "gore-and-ash-async-1.1.1.0-2OVkZlWWiw2AoycryFpZ3T" True) (C1 (MetaCons "AsyncId" PrefixI True) (S1 (MetaSel (Just Symbol "unAsyncId") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int)))

class (MonadIO m, MonadThrow m) => MonadAsync m where

Low level monadic API for module.

Note: does not require m to be IO monad.

Minimal complete definition

asyncActionM, asyncActionBoundM, asyncPollM, asyncCancelM, asyncSyncActionM, asyncSyncPollM, asyncSyncCanceM

Methods

asyncActionM :: Typeable a => IO a -> m AsyncId

Start execution of IO action concurrently and return its id

asyncActionBoundM :: Typeable a => IO a -> m AsyncId

Start execution of IO action concurrently and return its id

Note: forks thread within same OS thread.

asyncPollM :: Typeable a => AsyncId -> m (Maybe (Either SomeException a))

Check state of concurrent value

Could throw MonadAsyncExcepion, AsyncWrongType and AsyncNotFound constructors.

asyncCancelM :: AsyncId -> m ()

Stops given async execution

asyncSyncActionM :: Typeable a => IO a -> m SyncId

Schedule action to be executed at the end of frame.

Use asyncSyncPollM to get result at next frame.

Note: order of IO actions is preserved.

asyncSyncPollM :: Typeable a => SyncId -> m (Maybe (Either SomeException a))

Fires when given synchronious action is completed (at next frame after scheduling)

Could throw MonadAsyncExcepion, SyncWrongType constructor.

asyncSyncCanceM :: SyncId -> m ()

Unshedule given action from execution

Actually you can unshedule it until end of frame when corresponding asyncSyncActionM was called.

Instances

(MonadIO (mt m), MonadThrow (mt m), MonadAsync m, MonadTrans mt) => MonadAsync (mt m)

Methods

asyncActionM :: Typeable * a => IO a -> mt m AsyncId

asyncActionBoundM :: Typeable * a => IO a -> mt m AsyncId

asyncPollM :: Typeable * a => AsyncId -> mt m (Maybe (Either SomeException a))

asyncCancelM :: AsyncId -> mt m ()

asyncSyncActionM :: Typeable * a => IO a -> mt m SyncId

asyncSyncPollM :: Typeable * a => SyncId -> mt m (Maybe (Either SomeException a))

asyncSyncCanceM :: SyncId -> mt m ()

(MonadIO m, MonadThrow m) => MonadAsync (AsyncT s m)

Methods

asyncActionM :: Typeable * a => IO a -> AsyncT s m AsyncId

asyncActionBoundM :: Typeable * a => IO a -> AsyncT s m AsyncId

asyncPollM :: Typeable * a => AsyncId -> AsyncT s m (Maybe (Either SomeException a))

asyncCancelM :: AsyncId -> AsyncT s m ()

asyncSyncActionM :: Typeable * a => IO a -> AsyncT s m SyncId

asyncSyncPollM :: Typeable * a => SyncId -> AsyncT s m (Maybe (Either SomeException a))

asyncSyncCanceM :: SyncId -> AsyncT s m ()

Arrow API

Not bounded async

asyncAction :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event a)

Execute given IO action concurrently. Event fires once when the action is finished. Exceptions are rethrown into main thread.

asyncActionC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event a)

Execute given IO action concurrently. Event fires once when the action is finished. Exceptions are rethrown into main thread.

The concurrent action can be canceled by input event.

asyncActionEx :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event (Either SomeException a))

Execute given IO action concurrently.

Event fires once when the action is finished. Exceptions in the concurrent action are returned in event payload.

asyncActionExC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event (Either SomeException a))

Execute given IO action concurrently.

Event fires once when the action is finished. Exceptions in the concurrent action are returned in event payload.

The concurrent action can be canceled by input event.

asyncActionFactory :: (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq a))

Wire that executes incoming IO actions concurrently and then produces events with results once for each action.

Exceptions are rethrown into main thread.

asyncActionFactoryEx :: (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq (Either SomeException a)))

Wire that executes incoming IO actions concurrently and then produces events with results once for each action.

Exceptions are returned in event payload.

Bounded async

asyncActionBound :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event a)

Execute given IO action concurrently. Event fires once when the action is finished. Exceptions are rethrown into main thread.

Note: forks thread within same OS thread.

asyncActionBoundC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event a)

Execute given IO action concurrently. Event fires once when the action is finished. Exceptions are rethrown into main thread.

The concurrent action can be canceled by input event.

Note: forks thread within same OS thread.

asyncActionBoundEx :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event (Either SomeException a))

Execute given IO action concurrently.

Event fires once when the action is finished. Exceptions in the concurrent action are returned in event payload.

Note: forks thread within same OS thread.

asyncActionBoundExC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event (Either SomeException a))

Execute given IO action concurrently.

Event fires once when the action is finished. Exceptions in the concurrent action are returned in event payload.

The concurrent action can be canceled by input event.

Note: forks thread within same OS thread.`

asyncActionBoundFactory :: (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq a))

Wire that executes incoming IO actions concurrently and then produces events with results once for each action.

Exceptions are rethrown into main thread.

Note: forks thread within same OS thread.

asyncActionBoundFactoryEx :: (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq (Either SomeException a)))

Wire that executes incoming IO actions concurrently and then produces events with results once for each action.

Exceptions are returned in event payload.

Note: forks thread within same OS thread.

Sync actions

asyncSyncAction :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event a)

Execute given IO action at end of current frame. Event fires once at next frame.

Exceptions are rethrown into main thread.

asyncSyncActionEx :: (MonadAsync m, Typeable a) => IO a -> GameWire m b (Event (Either SomeException a))

Execute given IO action at end of current frame. Event fires once at next frame.

Exceptions are returned in event payload.

asyncSyncActionC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event a)

Execute given IO action at end of current frame. Event fires once at next frame.

Exceptions are rethrown into main thread.

Action can be canceled with input event, although you have only the frame to do this.

asyncSyncActionExC :: (MonadAsync m, Typeable a) => IO a -> GameWire m (Event b) (Event (Either SomeException a))

Execute given IO action at end of current frame. Event fires once at next frame.

Exceptions are rethrown into main thread.

Action can be canceled with input event, although you have only the frame to do this.

asyncSyncActionFactory :: forall m a. (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq a))

Wire that executes incoming IO actions at end of current frame and then produces events with results once for each action.

Exceptions are rethrown into main thread.

asyncSyncActionFactoryEx :: forall m a. (MonadAsync m, Typeable a) => GameWire m (Event (Seq (IO a))) (Event (Seq (Either SomeException a)))

Wire that executes incoming IO actions at end of current frame and then produces events with results once for each action.

Exceptions are rethrown into main thread.