Thank you for your comment

Beau­tiful Racket / explainers

Contracts

A contract oper­ates at run time and restricts the values that can pass across the boundary between two parts of a program. Contracts are primarily used with func­tions to check that input argu­ments and return values meet certain require­ments. This makes it easier to prevent the conse­quences of bad input, and locate the source of the problem.

For instance, here’s an irre­spon­sible our-div func­tion that allows 0 as a denom argu­ment. Bad input produces a generic error:

(define (our-div num denom)
  (/ num denom))
(our-div 42 0)
1
2
3
(define (our-div num denom)
  (/ num denom))
(our-div 42 0)
copy to clipboard
/: division by zero
1
/: division by zero
copy to clipboard

We can write a check for that argu­ment that gives more infor­ma­tion about the nature of the error and where it’s coming from:

(define (our-div num denom)
  (when (zero? denom)
    (error "our-div: denom argument needs to be nonzero"))
  (/ num denom))
(our-div 42 0)
1
2
3
4
5
(define (our-div num denom)
  (when (zero? denom)
    (error "our-div: denom argument needs to be nonzero"))
  (/ num denom))
(our-div 42 0)
copy to clipboard
our-div: denom argument needs to be nonzero
1
our-div: denom argument needs to be nonzero
copy to clipboard

Better still is a contract: it offers more compact & read­able nota­tion, more detail about the error, and takes care of all the under­lying house­keeping. The contract below says that the first argu­ment can be any number?, the second argu­ment must be a number? that is not zero?, and the return value must be a number?:

(require racket/contract) ; imports contract ingredients
(define/contract (our-div num denom)
  (number? (and/c number? (not/c zero?)) . -> . number?)
  (/ num denom))
(our-div 42 0)
1
2
3
4
5
(require racket/contract) ; imports contract ingredients
(define/contract (our-div num denom)
  (number? (and/c number? (not/c zero?)) . -> . number?)
  (/ num denom))
(our-div 42 0)
copy to clipboard
our-div: contract violation
  expected: (not/c zero?)
  given: 0
  in: an and/c case of
      the 2nd argument of
      (->
       number?
       (and/c number? (not/c zero?))
       number?)
  contract from: (function our-div)
  blaming: anonymous-module
   (assuming the contract is correct)
  at: unsaved-editor:3.18
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
our-div: contract violation
  expected: (not/c zero?)
  given: 0
  in: an and/c case of
      the 2nd argument of
      (->
       number?
       (and/c number? (not/c zero?))
       number?)
  contract from: (function our-div)
  blaming: anonymous-module
   (assuming the contract is correct)
  at: unsaved-editor:3.18
copy to clipboard

Bound­aries

A func­tion contract can be posi­tioned at one of two bound­aries (and in either place, we have to require racket/contract into the module):

  1. At a module boundary, using contract-out with provide. In this case, only the calls to the func­tion from outside the module will invoke the contract:

    (module divs br
      (require racket/contract)
      (provide
       (contract-out
        [int-div (integer? integer? . -> . integer?)]))
      (define (int-div num denom)
        (/ num denom))

      (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
        (displayln (int-div 42 2.5))))

    (require (submod "." divs))
    (with-handlers ([exn:fail? (λ (e) 'outer-breach)])
      (displayln (int-div 42 2.5)))
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    (module divs br
  (require racket/contract)
  (provide
   (contract-out
    [int-div (integer? integer? . -> . integer?)]))
  (define (int-div num denom)
    (/ num denom))

  (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
    (displayln (int-div 42 2.5))))

(require (submod "." divs))
(with-handlers ([exn:fail? (λ (e) 'outer-breach)])
  (displayln (int-div 42 2.5)))
    copy to clipboard
    16.8 ; no contract invoked from within the module
    'outer-breach
    1
2
    16.8 ; no contract invoked from within the module
'outer-breach
    copy to clipboard

    A module-boundary contract doesn’t have to live in the module where the func­tion is defined. Here, the usual / func­tion from br is re-exported with a more restric­tive contract attached:

    (module divs br
      (require racket/contract)
      (provide
       (contract-out
        [/ (integer? integer? . -> . integer?)]))

      (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
        (displayln (/ 42 2.5))))

    (require (submod "." divs))
    (with-handlers ([exn:fail? (λ (e) 'outer-breach)])
      (displayln (/ 42 2.5)))
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    (module divs br
  (require racket/contract)
  (provide
   (contract-out
    [/ (integer? integer? . -> . integer?)]))

  (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
    (displayln (/ 42 2.5))))

(require (submod "." divs))
(with-handlers ([exn:fail? (λ (e) 'outer-breach)])
  (displayln (/ 42 2.5)))
    copy to clipboard
    16.8 ; no contract invoked from within the module
    'outer-breach
    1
2
    16.8 ; no contract invoked from within the module
'outer-breach
    copy to clipboard

  2. At the func­tion boundary, using define/contract. Every call to the func­tion will trigger the contract, even within the module. Below, int-div has a contract for integer? input and output. When called with a floating-point argu­ment, whether inside or outside the submodule, it will cause an error:  + For demon­stra­tion purposes, we’re trap­ping these errors using with-handlers. See errors and excep­tions.

    (module divs br
      (require racket/contract)
      (provide int-div)
      (define/contract (int-div num denom)
        (integer? integer? . -> . integer?)
        (/ num denom))

      (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
        (displayln (int-div 42 2.5))))

    (require (submod "." divs))
    (with-handlers ([exn:fail? (λ (e) 'outer-breach)])
      (displayln (int-div 42 2.5)))
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    (module divs br
  (require racket/contract)
  (provide int-div)
  (define/contract (int-div num denom)
    (integer? integer? . -> . integer?)
    (/ num denom))

  (with-handlers ([exn:fail? (λ (e) 'inner-breach)])
    (displayln (int-div 42 2.5))))

(require (submod "." divs))
(with-handlers ([exn:fail? (λ (e) 'outer-breach)])
  (displayln (int-div 42 2.5)))
    copy to clipboard
    'inner-breach
    'outer-breach
    1
2
    'inner-breach
'outer-breach
    copy to clipboard

More exotic combi­na­tions are possible. For instance, we could make a safe submodule for a given module that exports all the same bind­ings, but with contracts added. Then the user could choose whether to import that module with or without its contracts active, by choosing to require either the usual module-name or (submod module-name safe).

Combi­na­tors

A func­tion contract consists of a combi­nator followed by pred­i­cates—one pred­i­cate corre­sponding to each input argu­ment, then one more corre­sponding to the return value. For a func­tion with a fixed number of argu­ments (aka fixed arity), use the -> combi­nator:

(define/contract (f str int)
  (-> string? integer? number?)
  42)
copy to clipboard

This contract would be used with a func­tion that takes two argu­ments—a string? and an integer?—and returns a number?. For read­ability, it’s conven­tional to write contracts using Racket’s infix nota­tion, so this contract could be written like so:

(define/contract (f str int)
  (string? integer? . -> . number?)
  42)
1
2
3
(define/contract (f str int)
  (string? integer? . -> . number?)
  42)
copy to clipboard

Keyword argu­ments are handled by appending the keyword name to the contract pred­i­cate:

(define/contract (f #:this str #:that int)
  (#:this string? #:that integer? . -> . number?)
  42)
1
2
3
(define/contract (f #:this str #:that int)
  (#:this string? #:that integer? . -> . number?)
  42)
copy to clipboard

If the func­tion has optional argu­ments, use the ->* combi­nator. The manda­tory and optional argu­ments are grouped into their own paren­the­sized sublists. So a func­tion with two manda­tory string argu­ments and an optional integer argu­ment would have this contract:

(define/contract (f str str2 [int 0])
  ((string? string?) (integer?) . ->* . number?)
  42)
1
2
3
(define/contract (f str str2 [int 0])
  ((string? string?) (integer?) . ->* . number?)
  42)
copy to clipboard

A contract that includes a rest argu­ment must use the ->* combi­nator (because a rest argu­ment is always optional) with the #:rest keyword:

(define/contract (f str . ints)
  ((string?) () #:rest (listof integer?) . ->* . number?)
  42)
1
2
3
(define/contract (f str . ints)
  ((string?) () #:rest (listof integer?) . ->* . number?)
  42)
copy to clipboard

Pred­i­cates

A pred­i­cate is a func­tion that takes any single value and returns a Boolean. Any pred­i­cate can be used within a contract—either pred­i­cates from the Racket library, or ones you create (use any/c in a contract to accept any value):

(require racket/contract)
(define/contract (divisible-by-3? x)
  (any/c . -> . boolean?)
  (zero? (modulo x 3)))

(define/contract (f x)
  (divisible-by-3? . -> . integer?)
  x)
(f 6) ; 6
(f 3) ; 3
(f 4) ; contract violation (not `divisible-by-3?`)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
(require racket/contract)
(define/contract (divisible-by-3? x)
  (any/c . -> . boolean?)
  (zero? (modulo x 3)))

(define/contract (f x)
  (divisible-by-3? . -> . integer?)
  x)
(f 6) ; 6
(f 3) ; 3
(f 4) ; contract violation (not `divisible-by-3?`)
copy to clipboard

The contract library also provides tools for refining pred­i­cates, like or/c, and/c, and not/c:

(require racket/contract)
(define (divisible-by-3? x) (zero? (modulo x 3)))

(define/contract (f x)
  ((and/c divisible-by-3? even?) . -> . (not/c flonum?))
  x)

(f 6) ; 6
(f 6.0) ; contract violation (not `(not/c flonum?)`)
(f 3) ; contract violation (not `even?`)
(f 4) ; contract violation (not `divisible-by-3?`)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
(require racket/contract)
(define (divisible-by-3? x) (zero? (modulo x 3)))

(define/contract (f x)
  ((and/c divisible-by-3? even?) . -> . (not/c flonum?))
  x)

(f 6) ; 6
(f 6.0) ; contract violation (not `(not/c flonum?)`)
(f 3) ; contract violation (not `even?`)
(f 4) ; contract violation (not `divisible-by-3?`)
copy to clipboard

For lists and vectors, the contract library offers listof and vectorof, which check the members of these struc­tures:

(require racket/contract)
(define (divisible-by-3? x) (zero? (modulo x 3)))

(define/contract (f . xs)
  (() () #:rest (listof divisible-by-3?) . ->* . any/c)
  xs)

(f 6 3) ; '(6 3)
(f 9 27 81) ; '(9 27 81)
(f 3 6 4 9 27) ; contract violation (4 is not `divisible-by-3?`)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
(require racket/contract)
(define (divisible-by-3? x) (zero? (modulo x 3)))

(define/contract (f . xs)
  (() () #:rest (listof divisible-by-3?) . ->* . any/c)
  xs)

(f 6 3) ; '(6 3)
(f 9 27 81) ; '(9 27 81)
(f 3 6 4 9 27) ; contract violation (4 is not `divisible-by-3?`)
copy to clipboard

But there is a price

“If contracts are so great, why don’t we use them all the time?” Because they’re not free.  + A Lisp programmer knows the value of every­thing, but the cost of nothing.
—Alan Perlis (chan­neling Oscar Wilde) A contract oper­ates at run time, so it neces­sarily imposes a perfor­mance cost. Contracts offer the tradeoff—that we often encounter in program­ming—between safety and speed.

Contracts can impose unrea­son­able costs in three situ­a­tions:

  1. If a func­tion is frequently called, then its contract will be too. The speed of that contract will have an outsize effect on the overall program. (Espe­cially because it’s not uncommon to find that the contract takes more time than the rest of the func­tion.)

    Possible solu­tion: write the argu­ment checking by hand. Helper func­tions like raise-argument-error can create the same type of error a contract would (though slightly less descrip­tive):

    (define (our-div num denom)
      (unless (and (number? denom) (not (zero? denom)))
        (raise-argument-error
         'our-div
         "nonzero number for denom"
         denom))
      (/ num denom))
    (our-div 42 0)
    1
2
3
4
5
6
7
8
    (define (our-div num denom)
  (unless (and (number? denom) (not (zero? denom)))
    (raise-argument-error
     'our-div
     "nonzero number for denom"
     denom))
  (/ num denom))
(our-div 42 0)
    copy to clipboard
    our-div: contract violation
      expected: nonzero number for denom
      given: 0
    1
2
3
    our-div: contract violation
  expected: nonzero number for denom
  given: 0
    copy to clipboard

  2. A contract is a func­tion that calls a series of other func­tions to test its argu­ments. If those func­tions are them­selves slow, then the contract will be too. Possible solu­tion: simplify the contract to use faster checks.

  3. If the data struc­tures that pass through the contract boundary tend to be huge (like giant lists), any contract that checks every element (like listof) will be slow. Possible solu­tion: package the data into a struc­ture type, which can be tested quickly, because it has its own pred­i­cate.

Of course, any contract installed at a func­tion boundary (with define/contract) will likely be called more often than one installed at a module boundary (with contract-out). Choosing bound­aries wisely will improve perfor­mance by only using the contract where it’s needed most.

Following that logic, func­tions that touch the public inter­face of a program are likely to benefit more from contracts (because they have less control over their input) than func­tions that only touch the private inter­face.

Further

← prev next →