Contract Profiling
contract-profile
contract-profile-thunk
6.10

Contract Profiling

This package provides support for profiling the execution of Contracts.

Contracts are a great mechanism for enforcing invariants and producing good error messages, but they introduce run-time checking which may impose significant costs. The goal of the contract profiler is to identify where these costs are, and provide information to help control them.

The simplest way to use this tool is to use the raco contract-profile command, which takes a file name as argument, and runs the contract profiler on the main submodule of that file (if it exists), or on the module itself (if there is no main submodule). The tool’s output is decribed below.

 (require contract-profile) package: contract-profile

In addition to using raco contract-profile, it is possible to invoke the contract profiler programmatically. This allows for profiling particular portions of programs, and for controlling the output.

syntax

(contract-profile option ... body ...)

 
option = #:module-graph-view-file module-graph-view-file
  | #:boundary-view-file boundary-view-file
  | #:boundary-view-key-file boundary-view-key-file
  | #:report-space-efficient? report-space-efficient?
Produces a report of the performance costs related to contract checking in body on standard output.

Specifically, displays the proportion of body’s running time that was spent checking contracts and breaks that time down by contract, and then breaks down the cost of each contract between the different contracted values that use it.

If report-space-efficient? is non-false, space-efficient contracts are marked specially in the report. When using raco contract-profile, this is controlled using the --report-space-efficient flag.

Additional visualizations are available on-demand, controlled by keyword arguments which specify their destination files. An argument of #f (the default) disables that visualization.

procedure

(contract-profile-thunk 
  thunk 
  [#:module-graph-view-file module-graph-view-file 
  #:boundary-view-file boundary-view-file 
  #:boundary-view-key-file boundary-view-key-file 
  #:report-space-efficient? report-space-efficient?]) 
  any
  thunk : (-> any)
  module-graph-view-file : (or/c path-string #f) = #f
  boundary-view-file : (or/c path-string #f) = #f
  boundary-view-key-file : (or/c path-string #f) = #f
  report-space-efficient? : any/c = #f
Like contract-profile, but as a function which takes a thunk to profile as argument.

Examples:
> (define/contract (sum* numbers)
    (-> (listof integer?) integer?)
    (for/fold ([total 0])
              ([n (in-list numbers)])
      (+ total n)))
> (contract-profile (sum* (range (expt 10 7))))

Running time is 20.68% contracts

529/2555 ms

(-> (listof integer?) integer?)                                  528.5 ms

#<blame>::-1                                                    

    sum*                                                         528.5 ms

49999995000000

> (define/contract (vector-max* vec-of-numbers)
    (-> (vectorof list?) integer?)
    (for/fold ([total 0])
              ([numbers (in-vector vec-of-numbers)])
      (+ total (sum* numbers))))
> (contract-profile (vector-max* (make-vector 10 (range (expt 10 7)))))

Running time is 93.25% contracts

4453/4775 ms

(-> (vectorof (listof any/c)) integer?)                          2055.5 ms

#<blame>::-1                                                    

    vector-max*                                                  2055.5 ms

(-> (listof integer?) integer?)                                  2397 ms

#<blame>::-1                                                    

    sum*                                                         2397 ms

499999950000000