{-# LANGUAGE CPP        #-}
{-# LANGUAGE Rank2Types #-}
-- |
-- Module      :  FRP.Yampa.Task
-- Copyright   :  (c) Ivan Perez, 2014-2022
--                (c) George Giorgidze, 2007-2012
--                (c) Henrik Nilsson, 2005-2006
--                (c) Antony Courtney and Henrik Nilsson, Yale University, 2003-2004
-- License     :  BSD-style (see the LICENSE file in the distribution)
--
-- Maintainer  :  ivan.perez@keera.co.uk
-- Stability   :  provisional
-- Portability :  non-portable (GHC extensions)
--
-- Task abstraction on top of signal transformers.
module FRP.Yampa.Task
    ( Task
    , mkTask
    , runTask
    , runTask_
    , taskToSF
    , constT
    , sleepT
    , snapT
    , timeOut
    , abortWhen
    )
  where

#if __GLASGOW_HASKELL__ < 710
import Control.Applicative (Applicative(..))
#endif

import FRP.Yampa.Basic        (constant)
import FRP.Yampa.Diagnostics  (intErr, usrErr)
import FRP.Yampa.Event        (Event, lMerge)
import FRP.Yampa.EventS       (after, edgeBy, never, snap)
import FRP.Yampa.InternalCore (SF, Time, arr, first, (&&&), (>>>))
import FRP.Yampa.Switches     (switch)

infixl 0 `timeOut`, `abortWhen`

-- * The Task type

-- | A task is a partially SF that may terminate with a result.

newtype Task a b c =
  -- CPS-based representation allowing termination to be detected.
  -- (Note the rank 2 polymorphic type!)
  -- The representation can be changed if necessary, but the Monad laws
  -- follow trivially in this case.
  Task (forall d . (c -> SF a (Either b d)) -> SF a (Either b d))

unTask :: Task a b c -> ((c -> SF a (Either b d)) -> SF a (Either b d))
unTask :: forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask (Task forall d. (c -> SF a (Either b d)) -> SF a (Either b d)
f) = forall d. (c -> SF a (Either b d)) -> SF a (Either b d)
f

-- | Creates a 'Task' from an SF that returns, as a second output, an 'Event'
-- when the SF terminates. See 'switch'.
mkTask :: SF a (b, Event c) -> Task a b c
mkTask :: forall a b c. SF a (b, Event c) -> Task a b c
mkTask SF a (b, Event c)
st = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (forall a b c. SF a (b, Event c) -> (c -> SF a b) -> SF a b
switch (SF a (b, Event c)
st forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c d.
Arrow a =>
a b c -> a (b, d) (c, d)
first (forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a b. a -> Either a b
Left)))

-- | Runs a task.
--
-- The output from the resulting signal transformer is tagged with Left while
-- the underlying task is running. Once the task has terminated, the output
-- goes constant with the value Right x, where x is the value of the
-- terminating event.

-- Check name.
runTask :: Task a b c -> SF a (Either b c)
runTask :: forall a b c. Task a b c -> SF a (Either b c)
runTask Task a b c
tk = (forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask Task a b c
tk) (forall b a. b -> SF a b
constant forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a b. b -> Either a b
Right)

-- | Runs a task that never terminates.
--
-- The output becomes undefined once the underlying task has terminated.
--
-- Convenience function for tasks which are known not to terminate.
runTask_ :: Task a b c -> SF a b
runTask_ :: forall a b c. Task a b c -> SF a b
runTask_ Task a b c
tk = forall a b c. Task a b c -> SF a (Either b c)
runTask Task a b c
tk
              forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either forall a. a -> a
id (forall a. String -> String -> String -> a
usrErr String
"YampaTask" String
"runTask_"
                                         String
"Task terminated!"))

-- | Creates an SF that represents an SF and produces an event
-- when the task terminates, and otherwise produces just an output.
taskToSF :: Task a b c -> SF a (b, Event c)
taskToSF :: forall a b c. Task a b c -> SF a (b, Event c)
taskToSF Task a b c
tk = forall a b c. Task a b c -> SF a (Either b c)
runTask Task a b c
tk
              forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> (forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either forall a. a -> a
id (forall a. String -> String -> String -> a
usrErr String
"YampaTask" String
"runTask_"
                                          String
"Task terminated!"))
                   forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall a b. (a -> a -> Maybe b) -> a -> SF a (Event b)
edgeBy forall {a} {b} {a} {a}. Either a b -> Either a a -> Maybe a
isEdge (forall a b. a -> Either a b
Left forall a. HasCallStack => a
undefined))
  where
    isEdge :: Either a b -> Either a a -> Maybe a
isEdge (Left a
_)  (Left a
_)  = forall a. Maybe a
Nothing
    isEdge (Left a
_)  (Right a
c) = forall a. a -> Maybe a
Just a
c
    isEdge (Right b
_) (Right a
_) = forall a. Maybe a
Nothing
    isEdge (Right b
_) (Left a
_)  = forall a. Maybe a
Nothing

-- * Functor, Applicative and Monad instance

instance Functor (Task a b) where
  fmap :: forall a b. (a -> b) -> Task a b a -> Task a b b
fmap a -> b
f Task a b a
tk = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (\b -> SF a (Either b d)
k -> forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask Task a b a
tk (b -> SF a (Either b d)
k forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> b
f))

instance Applicative (Task a b) where
  pure :: forall a. a -> Task a b a
pure a
x  = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (\a -> SF a (Either b d)
k -> a -> SF a (Either b d)
k a
x)
  Task a b (a -> b)
f <*> :: forall a b. Task a b (a -> b) -> Task a b a -> Task a b b
<*> Task a b a
v = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (\b -> SF a (Either b d)
k -> (forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask Task a b (a -> b)
f) (\a -> b
c -> forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask Task a b a
v (b -> SF a (Either b d)
k forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> b
c)))

instance Monad (Task a b) where
  Task a b a
tk >>= :: forall a b. Task a b a -> (a -> Task a b b) -> Task a b b
>>= a -> Task a b b
f = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (\b -> SF a (Either b d)
k -> forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask Task a b a
tk (\a
c -> forall a b c d.
Task a b c -> (c -> SF a (Either b d)) -> SF a (Either b d)
unTask (a -> Task a b b
f a
c) b -> SF a (Either b d)
k))
  return :: forall a. a -> Task a b a
return a
x = forall a b c.
(forall d. (c -> SF a (Either b d)) -> SF a (Either b d))
-> Task a b c
Task (\a -> SF a (Either b d)
k -> a -> SF a (Either b d)
k a
x)

-- Let's check the monad laws:
--
--   t >>= return
--   = \k -> t (\c -> return c k)
--   = \k -> t (\c -> (\x -> \k -> k x) c k)
--   = \k -> t (\c -> (\x -> \k' -> k' x) c k)
--   = \k -> t (\c -> k c)
--   = \k -> t k
--   = t
--   QED
--
--   return x >>= f
--   = \k -> (return x) (\c -> f c k)
--   = \k -> (\k -> k x) (\c -> f c k)
--   = \k -> (\k' -> k' x) (\c -> f c k)
--   = \k -> (\c -> f c k) x
--   = \k -> f x k
--   = f x
--   QED
--
--   (t >>= f) >>= g
--   = \k -> (t >>= f) (\c -> g c k)
--   = \k -> (\k' -> t (\c' -> f c' k')) (\c -> g c k)
--   = \k -> t (\c' -> f c' (\c -> g c k))
--   = \k -> t (\c' -> (\x -> \k' -> f x (\c -> g c k')) c' k)
--   = \k -> t (\c' -> (\x -> f x >>= g) c' k)
--   = t >>= (\x -> f x >>= g)
--   QED
--
-- No surprises (obviously, since this is essentially just the CPS monad).

-- * Basic tasks

-- | Non-terminating task with constant output b.
constT :: b -> Task a b c
constT :: forall b a c. b -> Task a b c
constT b
b = forall a b c. SF a (b, Event c) -> Task a b c
mkTask (forall b a. b -> SF a b
constant b
b forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall a b. SF a (Event b)
never)

-- | "Sleeps" for t seconds with constant output b.
sleepT :: Time -> b -> Task a b ()
sleepT :: forall b a. Time -> b -> Task a b ()
sleepT Time
t b
b = forall a b c. SF a (b, Event c) -> Task a b c
mkTask (forall b a. b -> SF a b
constant b
b forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall b a. Time -> b -> SF a (Event b)
after Time
t ())

-- | Takes a "snapshot" of the input and terminates immediately with the input
-- value as the result.
--
-- No time passes; therefore, the following must hold:
--
-- @snapT >> snapT = snapT@

snapT :: Task a b a
snapT :: forall a b. Task a b a
snapT = forall a b c. SF a (b, Event c) -> Task a b c
mkTask (forall b a. b -> SF a b
constant (forall a. String -> String -> String -> a
intErr String
"YampaTask" String
"snapT" String
"Bad switch?") forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall a. SF a (Event a)
snap)

-- * Basic tasks combinators

-- | Impose a time out on a task.
timeOut :: Task a b c -> Time -> Task a b (Maybe c)
Task a b c
tk timeOut :: forall a b c. Task a b c -> Time -> Task a b (Maybe c)
`timeOut` Time
t = forall a b c. SF a (b, Event c) -> Task a b c
mkTask ((forall a b c. Task a b c -> SF a (b, Event c)
taskToSF Task a b c
tk forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall b a. Time -> b -> SF a (Event b)
after Time
t ()) forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall {a} {a} {a}. ((a, Event a), Event a) -> (a, Event (Maybe a))
aux)
  where
    aux :: ((a, Event a), Event a) -> (a, Event (Maybe a))
aux ((a
b, Event a
ec), Event a
et) = (a
b, (forall a. Event a -> Event a -> Event a
lMerge (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a. a -> Maybe a
Just Event a
ec) (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall a b. a -> b -> a
const forall a. Maybe a
Nothing) Event a
et)))

-- | Run a "guarding" event source (SF a (Event b)) in parallel with a
-- (possibly non-terminating) task.
--
-- The task will be aborted at the first occurrence of the event source (if it
-- has not terminated itself before that).
--
-- Useful for separating sequencing and termination concerns.  E.g. we can do
-- something "useful", but in parallel watch for a (exceptional) condition
-- which should terminate that activity, without having to check for that
-- condition explicitly during each and every phase of the activity.
--
-- Example: @tsk `abortWhen` lbp@
abortWhen :: Task a b c -> SF a (Event d) -> Task a b (Either c d)
Task a b c
tk abortWhen :: forall a b c d.
Task a b c -> SF a (Event d) -> Task a b (Either c d)
`abortWhen` SF a (Event d)
est = forall a b c. SF a (b, Event c) -> Task a b c
mkTask ((forall a b c. Task a b c -> SF a (b, Event c)
taskToSF Task a b c
tk forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& SF a (Event d)
est) forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall {a} {a} {b}.
((a, Event a), Event b) -> (a, Event (Either a b))
aux)
  where
    aux :: ((a, Event a), Event b) -> (a, Event (Either a b))
aux ((a
b, Event a
ec), Event b
ed) = (a
b, (forall a. Event a -> Event a -> Event a
lMerge (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. a -> Either a b
Left Event a
ec) (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. b -> Either a b
Right Event b
ed)))