@@ -523,10 +523,12 @@ assertST p = assert p $ return ()
523
523
-- Merging credits
524
524
--
525
525
526
- -- | Credits for keeping track of merge progress. These credits
527
- -- correspond directly to merge steps performed. We also call these \"physical\"
528
- -- credits (since they correspond to steps done), and as opposed to \"nominal\"
529
- -- credits in 'NominalCredit' and 'NominalDebt'.
526
+ -- | Credits for keeping track of merge progress. These credits correspond
527
+ -- directly to merge steps performed.
528
+ --
529
+ -- We also call these \"physical\" credits (since they correspond to steps
530
+ -- done), and as opposed to \"nominal\" credits in 'NominalCredit' and
531
+ -- 'NominalDebt'.
530
532
type Credit = Int
531
533
532
534
-- | Debt for keeping track of the total merge work to do.
@@ -989,9 +991,32 @@ lookupsTree k = go
989
991
-- Nominal credits
990
992
--
991
993
994
+ -- | Nominal credit is the credit supplied to each level as we insert update
995
+ -- operations, one credit per update operation inserted.
996
+ --
997
+ -- Nominal credit must be supplied up to the 'NominalDebt' to ensure the merge
998
+ -- is complete.
999
+ --
1000
+ -- Nominal credits are a similar order of magnitude to physical credits (see
1001
+ -- 'Credit') but not the same, and we have to scale linearly to convert between
1002
+ -- them. Physical credits are the actual number of inputs to the merge, which
1003
+ -- may be somewhat more or somewhat less than the number of update operations
1004
+ -- we will insert before we need the merge to be complete.
1005
+ --
992
1006
newtype NominalCredit = NominalCredit Credit
993
1007
deriving stock Show
994
1008
1009
+ -- | The nominal debt for a merging run is the worst case (minimum) number of
1010
+ -- update operations we expect to insert before we expect the merge to be
1011
+ -- complete.
1012
+ --
1013
+ -- We require that an equal amount of nominal credit is supplied before we can
1014
+ -- expect a merge to be complete.
1015
+ --
1016
+ -- We scale linearly to convert nominal credits to physical credits, such that
1017
+ -- the nominal debt and physical debt are both considered \"100%\", and so that
1018
+ -- both debts are paid off at exactly the same time.
1019
+ --
995
1020
newtype NominalDebt = NominalDebt Credit
996
1021
deriving stock Show
997
1022
0 commit comments