Switch to Builder and Text

[FinleyMcIlwaine]

This is essentially a copy of #18, with the following minor fixes:

• The renderHtml' function was resulting in runtime errors due to negative stimes multipliers. I fixed this to avoid those.
• Some characters were being escaped differently than before (e.g. The '"' character was escaped as " instead of &quot). I changed this so the previous escaping behavior remains.

The above were detected by patching Haddock to use this patched xhtml and comparing test suite outputs for the HTML backend. There were no other diffs in Haddock's HTML output for its HTML test suite, other than unicode characters no longer being escaped and being printed literally in the HTML (which I believe is an acceptable change).

Performance

This patch improves Haddock's performance. I have gathered some metrics from the ghc-9.6 version of Haddock on the Agda codebase with just the HTML backend enabled. I ran haddock under the time command and used +RTS -s.

Baseline

The baseline performance metrics, without this patched xhtml, were:

  16,773,106,760 bytes allocated in the heap
   4,129,526,176 bytes copied during GC
     375,499,328 bytes maximum residency (15 sample(s))
       8,201,664 bytes maximum slop
            1056 MiB total memory in use (0 MiB lost due to fragmentation)

                                     Tot time (elapsed)  Avg pause  Max pause
  Gen  0      3894 colls,    28 par    1.696s   1.589s     0.0004s    0.0100s
  Gen  1        15 colls,     2 par    1.353s   1.286s     0.0857s    0.2306s

  Parallel GC work balance: 7.21% (serial 0%, perfect 100%)

  TASKS: 26 (1 bound, 25 peak workers (25 total), using -N8)

  SPARKS: 0 (0 converted, 0 overflowed, 0 dud, 0 GC'd, 0 fizzled)

  INIT    time    0.004s  (  0.004s elapsed)
  MUT     time    3.251s  (  3.793s elapsed)
  GC      time    3.049s  (  2.875s elapsed)
  EXIT    time    0.012s  (  0.010s elapsed)
  Total   time    6.317s  (  6.682s elapsed)

  Alloc rate    5,159,163,712 bytes per MUT second

  Productivity  51.5% of total user, 56.8% of total elapsed

        6.73 real         6.34 user         0.57 sys
          1256374272  maximum resident set size
                   0  average shared memory size
                   0  average unshared data size
                   0  average unshared stack size
              208387  page reclaims
                   1  page faults
                   0  swaps
                   0  block input operations
                   0  block output operations
                   0  messages sent
                   0  messages received
                   0  signals received
                 115  voluntary context switches
               19034  involuntary context switches
            57360348  instructions retired
            13287019  cycles elapsed
             1425920  peak memory footprint

6.73 seconds, 375,499,328 maximum live data residency, 1,256,374,272 maximum total residency, 16,773,106,760 total bytes allocated.

Patched

With Haddock patched to use this patched xhtml, the metrics were:

  17,786,284,096 bytes allocated in the heap
   2,567,164,456 bytes copied during GC
     353,392,488 bytes maximum residency (13 sample(s))
       7,978,016 bytes maximum slop
            1013 MiB total memory in use (0 MiB lost due to fragmentation)

                                     Tot time (elapsed)  Avg pause  Max pause
  Gen  0      3460 colls,  3007 par    1.161s   0.972s     0.0003s    0.0031s
  Gen  1        13 colls,     6 par    0.942s   0.540s     0.0416s    0.1284s

  Parallel GC work balance: 50.23% (serial 0%, perfect 100%)

  TASKS: 27 (1 bound, 26 peak workers (26 total), using -N8)

  SPARKS: 0 (0 converted, 0 overflowed, 0 dud, 0 GC'd, 0 fizzled)

  INIT    time    0.005s  (  0.005s elapsed)
  MUT     time    3.162s  (  3.408s elapsed)
  GC      time    2.104s  (  1.512s elapsed)
  EXIT    time    0.029s  (  0.004s elapsed)
  Total   time    5.299s  (  4.928s elapsed)

  Alloc rate    5,624,889,817 bytes per MUT second

  Productivity  59.7% of total user, 69.2% of total elapsed

        4.98 real         5.32 user         0.56 sys
          1212792832  maximum resident set size
                   0  average shared memory size
                   0  average unshared data size
                   0  average unshared stack size
              205719  page reclaims
                   1  page faults
                   0  swaps
                   0  block input operations
                   0  block output operations
                   0  messages sent
                   0  messages received
                   0  signals received
                  55  voluntary context switches
               25846  involuntary context switches
            57364956  instructions retired
            13026897  cycles elapsed
             1425920  peak memory footprint

4.98 seconds, 353,392,488 maximum live data residency, 1,212,792,832 maximum total residency, 17,786,284,096 total bytes allocated.

I consider this an improvement, with the caveat that total bytes allocated is up about 1GB. I have verified that the increase in total bytes allocated is coming from Haddock's HTML pretty-printing. I'm not sure if this is something to be concerned about, given the other performance improvements.

[cdornan]

I agree, that this looks like a clear improvement, even with the extra total allocation.

@parsonsmatt what do you think?

[FinleyMcIlwaine]

I am using this patch while writing other patches for Haddock and have still found no regressions in output or performance, including with Haddock's hyperlinked source backend.

[FinleyMcIlwaine]

@cdornan It would be great to have this merged, as I have some patches to Haddock on top of this pending. Please let me know if there is anything you would like me to do to help that happen 🙂

[cdornan]

Sorry for the delay — merging.