The seqaid package

[Tags:auto-instrumentation, bsd3, diagnostic, forcing, ghc-plugin, instrumentation, leak, library, parallel, program, remedial, space, strictness, tools]

Seqaid is a GHC plugin providing non-invasive auto-instrumentation of Haskell projects, for dynamic strictness (and parallelism) control. This will soon include optimisation for automated space leak relief using minimal strictification. [The optimiser is still in development however.]

Refer to the seqaid homepage for more information.

Please share your comments on this reddit discussion.


[Skip to Readme]

Properties

Versions 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6.0, 0.1.7.0, 0.2.0.0, 0.2.1.0, 0.2.1.1, 0.3.0.0, 0.3.0.1, 0.4.0.0
Change log changelog.txt
Dependencies array (>=0.4 && <0.6), base (==4.*), Cabal (>=1.10), containers (==0.5.*), cpphs (>=1.14), deepseq-bounded (>=0.8 && <1.0), directory (==1.2.*), exceptions (==0.5.*), filepath (==1.3.*), ghc (>=7.6 && <7.10), ghc-paths (==0.1.*), mtl (==2.*), process (==1.*), regex-base (<=0.93.2), regex-pcre (<=0.94.4), syb (<=0.4.2), template-haskell (==2.9.*), temporary (==1.2.*), transformers (==0.3.*) [details]
License BSD3
Author Andrew G. Seniuk
Maintainer Andrew Seniuk <rasfar@gmail.com>
Category Compiler Plugin
Home page http://fremissant.net/seqaid
Bug tracker http://fremissant.net/seqaid/trac
Uploaded Wed Feb 4 15:19:58 UTC 2015 by AndrewSeniuk
Distributions NixOS:0.4.0.0
Downloads 1661 total (36 in the last 30 days)
Votes
0 []
Status Docs uploaded by user
Build status unknown [no reports yet]

Modules

[Index]

Flags

NameDescriptionDefaultType
hello_hackage_visitor[Note to those reading on Hackage:] Please ignore these flags, which would be better presented in a collapsed state. The flags are mostly for development purposes.DisabledManual
ghc_710(Still broken for GHC 7.10.) Until I learn how to test GHC version in the .cabal file, we need a flag, since some build-depends must be excluded completely. (CPP testing __GLASGOW_HASKELL__ is then used the rest of the way, in the source files.)DisabledManual
sai_fork.DisabledManual
try_inject_noinline_on_requested_bindsIf we can prevent inlining of injected binds (without requiring user edits), that would probably be a good trade-off in terms of lost optimiser opportunities in exchange for assurance that the bind won't be inlined. This didn't work, and is a poor solution anyway.DisabledManual
seqable_onlyLike NFDATAN_ONLY, but for newer Seqable module.DisabledManual
th_type_in_types_annActually this is just preparatory, haven't gone down this road far yet. (We would like a TH.Type to Type.Type conversion function in the GHC API. Then we'd just send the list of Type.Type for direct use by the Core-plugin downstream).DisabledManual
seqaidpp_typesRather than choose types to seqinj for based on the types of the top-level binds, use seqaidpp to parse the types from seqaid.config. This stays on perpetually, finally, and could be removed soon.EnabledManual
infer_top_level_typesIf True, then TH will be used as it has been, to blanket-inject all top-level functions (at least, those not explicitly or implicitly excluded). Now, if False, only RHS's with result types in the "types" list for the module (in seqaid.config) will be wrapped (again, at least those not explicitly or implicitly excluded).DisabledManual
demo_modeThis is the only working mode so far. (And it only works when tested on the "leaky" package.) The switch exists to exclude hashable/hashtables deps (and subdeps) from the first release, while I can continue to work on this aspect in the development head.EnabledManual
dbg_seqaidWhen set, seqaidDispatch emits status lines periodically.EnabledManual
no_top_level_seqinj_dummiesIf have to inject a class and instance anyway to evade DCE, no need for the old top-level seqinj_ declarations (we hope...). (But it turned out they were all still needed.)DisabledManual
nfdatan_onlyTo simplify debugging.DisabledManual
show_typeInclude Typeable instance for (show . typeOf) in seqaidDispatchEnabledManual
use_cpphsThe original intention was to make this a non-manual flag, to allow the build system to try cpphs first, and if that fails, then to try system-wide cpp (typically GNU). Due to path problems, when the build client installs cpphs in the course of installing, it turns out to be better to use a shell script to delegate which cpp runs, jimmy options, etc.EnabledManual

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for seqaid

Readme for seqaid-0.4.0.0

  ----------------------------------------------------------

  Seqaid : Space Leak Diagnostic and Remedial Tool

  Andrew Seniuk
  rasfar@gmail.com
  2014

  ----------------------------------------------------------

  The easiest way to get started with seqaid is

     cabal install seqaid
     seqaid demo

  This will create a fresh directory, populate
  it with the <leaky> test project, and configure,
  build and run it with seqaid instrumentation.
  Consult the leaky.cabal, README, and leaky.hs files
  in that directory for additional information.
  (The README explains the console output.)

  ----------------------------------------------------------

  To instrument your own project ("myapp" for didactic purposes),
  typically the following steps suffice:

    1. cabal install seqaid, of course.

    2. Add the following (at the appropriate level of indentation)
       to your myapp.cabal file:

         default-extensions:  TemplateHaskell
         ghc-options:         -fplugin=Seqaid.Plugin
         ghc-options:         -F -pgmF seqaidpp
         ghc-options:         -with-rtsopts=-T

    3. Create a seqaid.config file in the project dir.
       The preprocessor will parse this, and control
       the extent of the instrumentation harness.

       There is no mechanism yet for real blanket
       instrumentation: You must name at least
       the modules you want instrumented, and the
       types you're interested in.  All binds in
       a module will be covered however.

       Looking at the seqaid.config file for leaky:

         package    leaky
         module     Main
           binds    duty
             types  Types.TA
         instances  Types.TA, Types.TB, Types.TC

       is this was changed to

         package    leaky
         module     Main
         types      Types.TA
         instances  Types.TA, Types.TB, Types.TC

       then all binds in module Main will be instrumented at
       all subexpressions having type Types.TA.

       The instances line names types you need to be able
       to force through.  If you get missing instance errors
       when you build, then you probably need to add those
       types to this list.

  ----------------------------------------------------------

  When the preprocessor runs, it will parse the configuration
  from seqaid.config, and perform the requisite insertions and
  substitutions behind the scenes.

    NOTE: This will never ever edit your source files directly!
    GHC takes care of running the preprocessor (-F option) on
    its own temporary files, in the natural course of the
    compilation pipeline.

  ----------------------------------------------------------

  The other project inseparable from this is <deepseq-bounded>.

  More specific information resides in
   - this document, and links from it:
       http://www.fremissant.net/deepseq-bounded-seqaid-leaky
   - reddit thread(s): http://www.reddit.com/r/haskell/comments/2pscxh/ann_deepseqbounded_seqaid_leaky/
   - the Haddock API docs for <seqaid> and <deepseq-bounded>
   - haskell.org mailing list thread(s), for instance:
       http://web.archiveorange.com/archive/v/nDNOvlhf3EjknkvBbCya

  And to a lesser extent, sporadic bits of information can also
  be found in files in the source distribution
   - the project README and .cabal files
   - comments in the source files [tend to obsolescence]

  Subsequent versions will hopefully be more cohesive.

  ----------------------------------------------------------