diff --git a/src/Fusion/Plugin/Types.hs b/src/Fusion/Plugin/Types.hs index 4f5ba40..07c6aea 100644 --- a/src/Fusion/Plugin/Types.hs +++ b/src/Fusion/Plugin/Types.hs @@ -21,7 +21,7 @@ module Fusion.Plugin.Types -- At most one annotation of each type is allowed per binding (attaching more -- than one of the same type is a compile error). Annotations of different -- types may be combined -- e.g. a binding may use both an - -- 'InspectPatternMatches' and an 'InspectAllocations' annotation to inspect + -- 'InspectPatternMatches' and an 'InspectConstructions' annotation to inspect -- both positions at once. -- ** Fusion Annotations @@ -32,9 +32,12 @@ module Fusion.Plugin.Types , NoFuse(..) -- ** Inspection Annotations - -- | Annotations to find fusion violations. + -- | Annotations to find fusion violations. Two simple rules hold regardless + -- of any other conditions: a type explicitly listed in a @Forbid...@ + -- annotation is always forbidden; a type explicitly listed in a @Permit...@ + -- annotation is always allowed. , InspectPatternMatches(..) - , InspectAllocations(..) + , InspectConstructions(..) , InspectTypeClasses(..) , MaxCoreSize(..) @@ -118,6 +121,12 @@ newtype NoFuseTypes = NoFuseTypes [Name] data NoFuse = NoFuse deriving (Eq, Data) +-- NOTE: Unboxed types are ignored by these inspection annotations by default. +-- The @inspect-unboxed@ plugin option turns on their inclusion module-wide, +-- which is usually sufficient. If in future per-binding control is wanted +-- instead, the names could take a @#@ suffix, for example +-- "PermitConstructions#". + -- | A GHC annotation attached to a specific top level binding (via an @ANN@ -- pragma on the binding, not on a type) that requests a fusion report for the -- types /pattern-matched/ (scrutinized, i.e. deconstructed in a @case@) in @@ -131,49 +140,39 @@ data NoFuse = NoFuse -- -- @ -- {-\# ANN function1 (ForbidPatternMatches [''Maybe]) #-} --- {-\# ANN function2 (ForbidFusedPatternMatches [''Maybe] [''Step]) #-} -- {-\# ANN function3 (PermitPatternMatches [''Int, ''IO]) #-} -- @ data InspectPatternMatches = ForbidPatternMatches [Name] - -- ^ Blocklist: report occurrences of exactly the named types found in a + -- ^ Blocklist: names explicitly listed here are not allowed to occur in -- scrutinizing or deconstructing (pattern-match, i.e. @case@) position in - -- the binding, regardless of whether they are annotated with 'Fuse'. + -- the binding. When the @forbid-fused@ plugin option is enabled, types + -- annotated with 'Fuse' are implictly added to this list. | PermitPatternMatches [Name] - -- ^ Allowlist: report every type pattern-matched in the binding except the - -- named types, which may appear freely. - | ForbidFusedPatternMatches [Name] [Name] - -- ^ Report pattern-match occurrences of every type annotated with 'Fuse' - -- found in the binding -- plus any types named in the first (forbid) list, - -- minus any types named in the second (allow) list. A name present in both - -- lists is allowed. + -- ^ Allowlist: names explicitly mentioned here are always allowed in + -- pattern matches in the binding. deriving (Eq, Data) -- | A GHC annotation attached to a specific top level binding (via an @ANN@ -- pragma on the binding, not on a type) that requests a fusion report for the --- types /allocated/ (constructed, i.e. built up) in that binding. +-- types /constructed/ (allocated, i.e. built up) in that binding. -- -- The same name rules as 'InspectPatternMatches' apply: use /type/ names -- (double quote, e.g. @''Int@), not data constructor names. -- -- @ --- {-\# ANN function1 (ForbidAllocations [''Maybe]) #-} --- {-\# ANN function2 (ForbidFusedAllocations [''Maybe] [''Step]) #-} --- {-\# ANN function3 (PermitAllocations [''Int, ''IO]) #-} +-- {-\# ANN function1 (ForbidConstructions [''Maybe]) #-} +-- {-\# ANN function3 (PermitConstructions [''Int, ''IO]) #-} -- @ -data InspectAllocations - = ForbidAllocations [Name] - -- ^ Blocklist: report occurrences of exactly the named types found in a - -- constructing (allocating) position in the binding, regardless of whether - -- they are annotated with 'Fuse'. - | PermitAllocations [Name] - -- ^ Allowlist: report every type constructed in the binding except the - -- named types, which may appear freely. - | ForbidFusedAllocations [Name] [Name] - -- ^ Report constructing occurrences of every type annotated with 'Fuse' - -- found in the binding -- plus any types named in the first (forbid) list, - -- minus any types named in the second (allow) list. A name present in both - -- lists is allowed. +data InspectConstructions + = ForbidConstructions [Name] + -- ^ Blocklist: names explicitly listed here are not allowed to occur in + -- constructing (usually leading to allocations) position in the binding. + -- When the @forbid-fused@ plugin option is enabled, types annotated with + -- 'Fuse' are implictly added to this list. + | PermitConstructions [Name] + -- ^ Allowlist: names explicitly mentioned here are always allowed in + -- constructing positions in the binding. deriving (Eq, Data) -- | A GHC annotation attached to a specific top level binding (via an @ANN@