deepseq-bounded: Bounded deepseq, including support for generic deriving

[ bsd3, control, library ] [ Propose Tags ] [ Report a vulnerability ]

This package provides methods for partially (or fully) evaluating data structures ("bounded deep evaluation").

More information is available on the project homepage. There may be activity on this reddit discussion, where your comments are invited.

Quoting from the deepseq package:

"Artificial forcing is often used for adding strictness to a program, e.g. in order to force pending exceptions, remove space leaks, or force lazy IO to happen. It is also useful in parallel programs, to ensure work does not migrate to the wrong thread."

Sometimes we don't want to, or cannot, force all the way, for instance when dealing with potentially infinite values of coinductive types. Also, bounded forcing bridges the theoretical axis between shallow seq and full deepseq.

We provide two new classes NFDataN and NFDataP. Instances of these provide bounded deep evaluation for arbitrary polytypic terms:

  • rnfn bounds the forced evaluation by depth of recursion.

  • rnfp forces based on patterns (static or dynamic).

Instances of NFDataN and NFDataP can be automatically derived via Generics.SOP, backed by the GNFDataN and GNFDataP modules. NFDataN can optionally be derived by the standard GHC.Generics facility (but not so for NFDataP).

Another approach is Seqable, which is similar to NFDataN, but optimised for use as a dynamically-reconfigurable forcing harness in the seqaid auto-instrumentation tool.

Recent developments supporting parallelisation control (in Pattern and Seqable modules) may justify renaming this library to something which encompasses both strictness and parallelism aspects.

NOTE: Versions >=0.6 are substantially different from the original (now deprecated) 0.5.* releases, particularly as regards NFDataP.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
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.
Disabled
haskell98_fragment

Sacrifice generic deriving, the NFDataPDyn module, and a couple functions from the PatUtil module, in exchange for true Haskell98 conformance (portability). (One non-H98 thing it insists on is PatternGuards, although this could be relieved in the obvious way, at the expense of code clarity.)

Disabled
use_par_patnode

On match, spark recursive submatching for parallel evaluation.

Enabled
use_pseq_patnode

Use Control.Parallel.pseq to order the evaluation of recursive submatching. This is done by providing a permutation argument; refer to the Control.DeepSeq.Bounded.Pattern.PatNode API for additional documentation. Configurable per PatNode.

Enabled
use_trace_patnode

Log a traceline to stderr en passant. Configurable per PatNode. Fires when node is pattern-matched, whether or not the match succeeds.

Enabled
use_ping_patnode

Raise an asynchronous exception en passant. This can be useful for gauging term shape relative to pattern shape, dynamically. Configurable per PatNode. Fires when node is pattern-matched, whether or not the match succeeds.

Enabled
use_die_patnode

Kill (just this) thread immediately. To kill the whole program from a pattern node match, use USE_PING_PATNODE, catch the exception in the main thread, and respond from there as you see fit. Configurable per PatNode. Fires when node is pattern-matched, whether or not the match succeeds.

Enabled
use_timing_patnode

Get as precise a measurement of the time of matching as possible, and optionally (depending on how you use the API) measuring and reporting (storing?) differential timestamps (relative to parent node already matched). Not sure how useable this will be (the timestamps need to be very high resolution and cheap enough to obtain), but the principle has its place here, and the flag makes it possible to exclude all this code in case it's not working out. Configurable per PatNode. Fires when node is pattern-matched, whether or not the match succeeds.

Enabled
overloaded_strings

Use the OverloadedStrings syntax extension, so never need to call compilePat explicitly. This gives the feeling of "bringing the DSL right into Haskell", and makes ghci experiments a lot less of a headache! Wish I'd had this in since the first release. I guess really nobody is experimenting with this at all, or surely they'd have clamoured for this!

Enabled
use_par_seqable

This flag (now) only affects Seqable. (Refer to USE_PAR_PATNODE for a comparable flag affecting NFDataP.) USE_PAR_SEQABLE = True depends on parallel, and permits (dynamically configurable) sparking of Sequable recursive demand propagation.

Enabled
just_alias_gseqable

The SOP generic function is probably more performant, anyway! (This will be forced False if HASKELL98_FRAGMENT is True.)

Enabled
just_alias_gnfdatan

The SOP generic function is probably more performant, anyway! (This will be forced False if HASKELL98_FRAGMENT is True.)

Disabled
just_alias_gnfdatap

The SOP generic function is probably more performant, anyway! (This will be forced False if HASKELL98_FRAGMENT is True.)

Disabled
provide_data_family

Provide a data family comprising instances corresponding to the Seqable, NFDataN and NFDataP modules. (This will be forced False if HASKELL98_FRAGMENT is True.)

Enabled
use_curly_brace_instead_of_paren_for_subpatterns

Choose grouping convention (concrete syntax) for pattern strings in the DSL. When True, you have "XX.*Y..Y" instead of the (new) default "((.*)..)". Where X=opening curly brace, and Y=closing curly brace - it seems Cabal makes it impossible to present a curly brace in a flag description, even escaped? Unless Unicode entities? { u007D } Nope.

Disabled
abbrev_wn_and_tn_concrete_syntax_to_number_alone__safe_only_to_depth_19

So you can write "2(!53)" instead of "*2(!*5*3)". This will be unambiguous up to a depth of 19. (It may still be unambiguous for higher depths, depending on the use case.) This could be convenient if you work a lot manually with the pattern DSL, particularly for vertical alignment of pattern structures, but otherwise it should be False as ambigities can develop, for instance under (showPat . shrinkPat . compilePat) iteration.

Disabled
abbrev_wn_and_tn_concrete_syntax_to_single_digit__can_only_express_down_to_depth_9

Similar to the preceding, but use "1" instead of "!" for depth-1, and moreover, use "0" instead of "." for depth-0. (This is such a niche-case syntax variant, that may as well go all the way!) It makes for very tidy when you're not using a lot of other attributes. This grammar variant is unambiguous; the danger here is only that conventions get mixed in practise...

Disabled
use_ww_deepseq

Depend on deepseq and deepseq-generics, to provide conditional deep forcing. This is optional.

Enabled
warn_pattern_match_failure

For NFDataP, if a pattern match fails a warning is output to stderr.

Disabled
use_sop

Use the generics-sop package instead of GHC.Generics (in GNFDataN) and instead of SYB (in NFDataPDyn). If USE_SOP is False, then NFDataPDyn, GNFDataP, and GSeqable modules will not be available.

Enabled
nfdata_instance_pattern

A flag to assist debugging, affecting a few modules.

Enabled
use_cpphs

The 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.

Enabled

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

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.6.0.0, 0.6.0.1, 0.6.0.2, 0.6.0.3, 0.6.1.0, 0.6.2.0, 0.7.0.0, 0.7.0.1, 0.7.0.2, 0.8.0.0 (info)
Change log changelog.txt
Dependencies array (>=0.5 && <0.6), base (>=4 && <5), cpphs (>=1.14), deepseq (>=1.3 && <1.5), deepseq-generics (>=0.1 && <0.2), generics-sop (>=0.1 && <0.2), mtl (>=2.1 && <2.2), parallel (>=3.2 && <3.3), random (==1.1), syb (<0.5) [details]
Tested with ghc ==7.6.3, ghc ==7.8.1, ghc ==7.8.3, ghc ==7.8.4, ghc ==7.10.1
License BSD-3-Clause
Author Andrew G. Seniuk
Maintainer Andrew Seniuk <rasfar@gmail.com>
Revised Revision 1 made by phadej at 2016-05-28T13:35:54Z
Category Control
Home page http://fremissant.net/deepseq-bounded
Bug tracker http://fremissant.net/deepseq-bounded/trac
Uploaded by AndrewSeniuk at 2015-02-04T15:19:46Z
Distributions
Reverse Dependencies 2 direct, 0 indirect [details]
Downloads 10825 total (56 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for deepseq-bounded-0.8.0.0

[back to package description]
For additional documentation, browse to ./HTML
(or http://www.fremissant.net/deepseq-bounded).