Safe Haskell	Safe-Inferred
Language	Haskell2010

Gargantext.Utils.Jobs.Monad

Contents

Types and classes
Reporting errors to users in a friendly way
Tracking jobs status
Functions

Synopsis

data JobEnv t w a = JobEnv {
- jeSettings :: JobSettings
- jeState :: JobsState t w a
- jeManager :: Manager
}
type NumRunners = Int
data JobError
- = InvalidIDType Text
- | IDExpired Int
- | InvalidMacID Text
- | UnknownJob Int
- | JobException SomeException
class MonadIO m => MonadJob m t w a | m -> t w a where
- getJobEnv :: m (JobEnv t w a)
class ToHumanFriendlyError e where
- mkHumanFriendly :: e -> Text
class MonadJobStatus m where
- type JobHandle m :: Type
- type JobType m :: Type
- type JobOutputType m :: Type
- type JobEventType m :: Type
- noJobHandle :: Proxy m -> JobHandle m
- getLatestJobStatus :: JobHandle m -> m (JobEventType m)
- withTracer :: Logger (JobEventType m) -> JobHandle m -> (JobHandle m -> m a) -> m a
- markStarted :: Int -> JobHandle m -> m ()
- markProgress :: Int -> JobHandle m -> m ()
- markFailure :: forall e. ToHumanFriendlyError e => Int -> Maybe e -> JobHandle m -> m ()
- markComplete :: JobHandle m -> m ()
- markFailed :: forall e. ToHumanFriendlyError e => Maybe e -> JobHandle m -> m ()
- addMoreSteps :: MonadJobStatus m => Int -> JobHandle m -> m ()
newJobEnv :: (EnumBounded t, Monoid w) => JobSettings -> Map t Prio -> Manager -> IO (JobEnv t w a)
defaultJobSettings :: NumRunners -> SecretKey -> JobSettings
genSecret :: IO SecretKey
getJobsSettings :: MonadJob m t w a => m JobSettings
getJobsState :: MonadJob m t w a => m (JobsState t w a)
getJobsMap :: MonadJob m t w a => m (JobMap (JobID 'Safe) w a)
getJobsQueue :: MonadJob m t w a => m (Queue t (JobID 'Safe))
queueJob :: (MonadJob m t w a, Ord t) => t -> i -> (JobID 'Safe -> i -> Logger w -> IO a) -> m (JobID 'Safe)
findJob :: MonadJob m t w a => JobID 'Safe -> m (Maybe (JobEntry (JobID 'Safe) w a))
checkJID :: MonadJob m t w a => JobID 'Unsafe -> m (Either JobError (JobID 'Safe))
withJob :: MonadJob m t w a => JobID 'Unsafe -> (JobID 'Safe -> JobEntry (JobID 'Safe) w a -> m r) -> m (Either JobError (Maybe r))
handleIDError :: MonadError e m => (JobError -> e) -> m (Either JobError a) -> m a
removeJob :: (Ord t, MonadJob m t w a) => Bool -> t -> JobID 'Safe -> m ()
markFailedNoErr :: MonadJobStatus m => JobHandle m -> m ()
markFailureNoErr :: MonadJobStatus m => Int -> JobHandle m -> m ()

Types and classes

data JobEnv t w a #

Constructors

JobEnv
Fields jeSettings :: JobSettings jeState :: JobsState t w a jeManager :: Manager

Instances

Instances details

MonadIO m => MonadJob (ReaderT (JobEnv t w a) m) t w a #
Instance details Defined in Gargantext.Utils.Jobs.Monad Methods getJobEnv :: ReaderT (JobEnv t w a) m (JobEnv t w a) #

type NumRunners = Int #

data JobError #

Constructors

InvalidIDType Text	We expected to find a job tagged internall as "job", but we found the input `T.Text` instead.
IDExpired Int	The given ID expired.
InvalidMacID Text
UnknownJob Int
JobException SomeException

Instances

Instances details

Show JobError #
Instance details Defined in Gargantext.Utils.Jobs.Monad Methods showsPrec :: Int -> JobError -> ShowS # show :: JobError -> String # showList :: [JobError] -> ShowS #

class MonadIO m => MonadJob m t w a | m -> t w a where #

Methods

getJobEnv :: m (JobEnv t w a) #

Instances

Instances details

MonadIO m => MonadJob (ReaderT (JobEnv t w a) m) t w a #
Instance details Defined in Gargantext.Utils.Jobs.Monad Methods getJobEnv :: ReaderT (JobEnv t w a) m (JobEnv t w a) #
MonadJob (GargM Env err) GargJob (Seq JobLog) JobLog #
Instance details Defined in Gargantext.API.Admin.EnvTypes Methods getJobEnv :: GargM Env err (JobEnv GargJob (Seq JobLog) JobLog) #

Reporting errors to users in a friendly way

class ToHumanFriendlyError e where #

This class represents the concept of "human friendly strings", by which we mean error messages and/or diagnostics which needs to be displayed to the end users, and, as such:

They should be easy to understand for end users, not developers (developers would access the full debug logs on the server machine). As such, they don't have to include implementation details and/or technicalities;
They MUST NOT include any sensitive data. Please be very careful when writing these instances because just calling "T.pack . show" on the input data is immediately wrong; things like Servant's ClientError or any HTTP exception might include api keys in the form of HTTP headers, so leaking that is BAD.

Methods

mkHumanFriendly :: e -> Text #

Instances

Instances details

ToHumanFriendlyError Void #
Instance details Defined in Gargantext.Utils.Jobs.Error Methods mkHumanFriendly :: Void -> Text #
ToHumanFriendlyError GetCorpusError #
Instance details Defined in Gargantext.Core.Text.Corpus.API Methods mkHumanFriendly :: GetCorpusError -> Text #
ToHumanFriendlyError ParseFormatError #
Instance details Defined in Gargantext.Core.Text.Corpus.Parsers Methods mkHumanFriendly :: ParseFormatError -> Text #
ToHumanFriendlyError HumanFriendlyErrorText #
Instance details Defined in Gargantext.Utils.Jobs.Error Methods mkHumanFriendly :: HumanFriendlyErrorText -> Text #

Tracking jobs status

class MonadJobStatus m where #

A monad to query for the status of a particular job and submit updates for in-progress jobs.

Associated Types

type JobHandle m :: Type #

This is type family for the concrete JobHandle that is associated to a job when it starts and it can be used to query for its completion status. Different environment can decide how this will look like.

type JobType m :: Type #

type JobOutputType m :: Type #

type JobEventType m :: Type #

Methods

noJobHandle :: Proxy m -> JobHandle m #

A job handle that doesn't do anything. Sometimes useful in all those circumstances where we need to test a function taking a JobHandle as input but we are not interested in the progress tracking.

getLatestJobStatus :: JobHandle m -> m (JobEventType m) #

Retrevies the latest JobEventType from the underlying monad. It can be used to query the latest status for a particular job, given its JobHandle as input.

withTracer :: Logger (JobEventType m) -> JobHandle m -> (JobHandle m -> m a) -> m a #

Adds an extra "tracer" that logs events to the passed action. Produces a new JobHandle.

markStarted :: Int -> JobHandle m -> m () #

Start tracking a new JobEventType with n remaining steps.

markProgress :: Int -> JobHandle m -> m () #

Mark n steps of the job as succeeded, while simultaneously substracting this number from the remaining steps.

markFailure :: forall e. ToHumanFriendlyError e => Int -> Maybe e -> JobHandle m -> m () #

Mark n step of the job as failed, while simultaneously substracting this number from the remaining steps. Attach an optional error message to the failure.

markComplete :: JobHandle m -> m () #

Finish tracking a job by marking all the remaining steps as succeeded.

markFailed :: forall e. ToHumanFriendlyError e => Maybe e -> JobHandle m -> m () #

Finish tracking a job by marking all the remaining steps as failed. Attach an optional message to the failure.

addMoreSteps :: MonadJobStatus m => Int -> JobHandle m -> m () #

Add n more steps to the running computation, they will be marked as remaining.

Instances

Instances details

MonadJobStatus (GargM DevEnv err) #
Instance details Defined in Gargantext.API.Admin.EnvTypes Associated Types type JobHandle (GargM DevEnv err) # type JobType (GargM DevEnv err) # type JobOutputType (GargM DevEnv err) # type JobEventType (GargM DevEnv err) # Methods noJobHandle :: Proxy (GargM DevEnv err) -> JobHandle (GargM DevEnv err) # getLatestJobStatus :: JobHandle (GargM DevEnv err) -> GargM DevEnv err (JobEventType (GargM DevEnv err)) # withTracer :: Logger (JobEventType (GargM DevEnv err)) -> JobHandle (GargM DevEnv err) -> (JobHandle (GargM DevEnv err) -> GargM DevEnv err a) -> GargM DevEnv err a # markStarted :: Int -> JobHandle (GargM DevEnv err) -> GargM DevEnv err () # markProgress :: Int -> JobHandle (GargM DevEnv err) -> GargM DevEnv err () # markFailure :: ToHumanFriendlyError e => Int -> Maybe e -> JobHandle (GargM DevEnv err) -> GargM DevEnv err () # markComplete :: JobHandle (GargM DevEnv err) -> GargM DevEnv err () # markFailed :: ToHumanFriendlyError e => Maybe e -> JobHandle (GargM DevEnv err) -> GargM DevEnv err () # addMoreSteps :: Int -> JobHandle (GargM DevEnv err) -> GargM DevEnv err () #
MonadJobStatus (GargM Env err) #
Instance details Defined in Gargantext.API.Admin.EnvTypes Associated Types type JobHandle (GargM Env err) # type JobType (GargM Env err) # type JobOutputType (GargM Env err) # type JobEventType (GargM Env err) # Methods noJobHandle :: Proxy (GargM Env err) -> JobHandle (GargM Env err) # getLatestJobStatus :: JobHandle (GargM Env err) -> GargM Env err (JobEventType (GargM Env err)) # withTracer :: Logger (JobEventType (GargM Env err)) -> JobHandle (GargM Env err) -> (JobHandle (GargM Env err) -> GargM Env err a) -> GargM Env err a # markStarted :: Int -> JobHandle (GargM Env err) -> GargM Env err () # markProgress :: Int -> JobHandle (GargM Env err) -> GargM Env err () # markFailure :: ToHumanFriendlyError e => Int -> Maybe e -> JobHandle (GargM Env err) -> GargM Env err () # markComplete :: JobHandle (GargM Env err) -> GargM Env err () # markFailed :: ToHumanFriendlyError e => Maybe e -> JobHandle (GargM Env err) -> GargM Env err () # addMoreSteps :: Int -> JobHandle (GargM Env err) -> GargM Env err () #

Functions

newJobEnv :: (EnumBounded t, Monoid w) => JobSettings -> Map t Prio -> Manager -> IO (JobEnv t w a) #

defaultJobSettings :: NumRunners -> SecretKey -> JobSettings #

genSecret :: IO SecretKey #

getJobsSettings :: MonadJob m t w a => m JobSettings #

getJobsState :: MonadJob m t w a => m (JobsState t w a) #

getJobsMap :: MonadJob m t w a => m (JobMap (JobID 'Safe) w a) #

getJobsQueue :: MonadJob m t w a => m (Queue t (JobID 'Safe)) #

queueJob :: (MonadJob m t w a, Ord t) => t -> i -> (JobID 'Safe -> i -> Logger w -> IO a) -> m (JobID 'Safe) #

findJob :: MonadJob m t w a => JobID 'Safe -> m (Maybe (JobEntry (JobID 'Safe) w a)) #

checkJID :: MonadJob m t w a => JobID 'Unsafe -> m (Either JobError (JobID 'Safe)) #

withJob :: MonadJob m t w a => JobID 'Unsafe -> (JobID 'Safe -> JobEntry (JobID 'Safe) w a -> m r) -> m (Either JobError (Maybe r)) #

handleIDError :: MonadError e m => (JobError -> e) -> m (Either JobError a) -> m a #

removeJob :: (Ord t, MonadJob m t w a) => Bool -> t -> JobID 'Safe -> m () #

markFailedNoErr :: MonadJobStatus m => JobHandle m -> m () #

Helper on top of markFailed for when we don't have a diagnostic to log.

markFailureNoErr :: MonadJobStatus m => Int -> JobHandle m -> m () #