Error.hs

-- | The library's fatal error type.
module Fragr.Error
  ( FragrError (..)
  ) where

import Control.Exception (Exception)
import Data.Text (Text)
import Type.Reflection (SomeTypeRep)

import Fragr.Types (FamilyId, SomeHandle)

{- |
API misuse is a programmer error and is reported by throwing this
exception. The 'Text' fields name the operation that detected the misuse.
-}
data FragrError
  = -- | access through a handle superseded by a later 'Fragr.Builder.write'
    StaleHandle Text SomeHandle
  | -- | 'Fragr.Builder.read' of a handle the same pass creates or writes
    ReadsOwnOutput SomeHandle
  | -- | the entry holds the first type, the caller requested the second
    TypeMismatch Text SomeTypeRep SomeTypeRep
  | -- | execution-time access to a handle the pass (named last) never declared
    Undeclared Text SomeHandle Text
  | HandleOutOfRange Int
  | ResourceIdOutOfRange Int
  | -- | execution attempted before 'Fragr.Compile.compile'
    NotCompiled Text
  | -- | 'Fragr.Execute.executeQueued' without a 'Fragr.Recycle.RecycleQueue', but the named transient needs deferred reclamation
    RecycleQueueRequired Text
  | -- | the named alias-group member is read (by the pass named last) before anything writes it ('Fragr.Compile.validateAliasGroups')
    AliasedReadBeforeWrite Text Text
  | -- | one version of the named resource is consumed on two distinct queue families ('Fragr.Compile.compileWith'), listed with each family's first consumer; a single owner cannot be released twice — 'Fragr.Graph.markShared' resources are exempt
    ReleasedToTwoFamilies Text [(Text, FamilyId)]
  | -- | a broken library invariant, not an API misuse
    InternalInvariant Text
  deriving stock (Show)

instance Exception FragrError