►The Racket Reference
▼8 Contracts
On this page:
get/  build-collapsible-late-neg-projection
collapsible-contract-continuation-mark-key
with-collapsible-contract-continuation-mark
prop:  collapsible-contract
collapsible-contract?
merge
collapsible-guard
collapsible-contract-property?
build-collapsible-contract-property
collapsible-ho/  c
collapsible-leaf/  c
impersonator-prop:  collapsible
has-impersonator-prop:  collapsible?
get-impersonator-prop:  collapsible
collapsible-property
collapsible-count-property
collapsible-wrapper-property
  top  contents  ← prev  up  next → 

8.10 Collapsible Contracts

 (require racket/contract/collapsible) package: base

Added in version 7.1.0.10 of package base.

Collapsible contracts are an optimization in the contract system designed to avoid a particular pathological build up of contract wrappers on higher-order values. The vectorof, vector/c, and -> contract combinators support collapsing for vector contracts and function contracts for functions returning a single value.

Intuitively, a collapsible contract is a tree structure. The tree nodes represent higher-order contracts (e.g., ->) and the tree leaves represent sequences of flat contracts. Two trees can collapse into one tree via the merge procedure, which removes unnecessary flat contracts from the leaves.

For more information on the motivation and design of collapsible contracts, see [Feltey18]. For the theoretical foundations, see [Greenberg15].

Warning: the features described in this section are experimental and may not be sufficient to implement new collapsible contracts. Implementing new collapsible contracts requires the use of unsafe chaperones and impersonators which are only supported for vector and procedure values. This documentation exists primarily to allow future maintenance of the racket/contract/collapsible library. End Warning

procedure

(get/build-collapsible-late-neg-projection c)

 → (-> blame? (values (-> any/c any/c any/c) collapsible-contract?))
  c : contract?
Returns the collapsible-late-neg projection for c.

If c does not have a collapsible-late-neg projection, then this function uses the original projection for it and constructs a leaf as its collapsible representation.

value

collapsible-contract-continuation-mark-key

 : continuation-mark-key?
Key used by continuation marks that are present during collapsible contract checking. The value of these marks are #t if the current contract is collapsible.

syntax

(with-collapsible-contract-continuation-mark body ...)

Inserts a continuation mark that informs the contract profiler that the current contract is collapsible.

value

prop:collapsible-contract : struct-type-property?

Structures implementing this property are usable as collapsible contracts. The value associated with this property should be constructed by calling build-collapsible-contract-property.

procedure

(collapsible-contract? v) → boolean?

  v : any/c
A predicate recognizing structures with the prop:collapsible-contract property.

procedure

(merge new-cc new-neg old-cc old-neg) → collapsible-contract?

  new-cc : collapsible-contract?
  new-neg : any/c
  old-cc : collapsible-contract?
  old-neg : any/c
Combine two collapsible contracts into a single collapsible contract. The new-neg and old-neg arguments are expected to be blame parties similar to those passed to a late neg projection.

procedure

(collapsible-guard cc val neg-party) → any/c

  cc : collapsible-contract?
  val : any/c
  neg-party : any/c
Similar to a late neg projection, this function guards the value val with the collapsible contract cc.

procedure

(collapsible-contract-property? v) → boolean?

  v : any/c
This predicate indicates that a value can be used as the property for prop:collapsible-contract.

procedure

(build-collapsible-contract-property 
  [#:try-merge try-merge 
  #:collapsible-guard collapsible-guard]) 
 → collapsible-contract-property?
  try-merge : 
(or/c #f
      (-> collapsible-contract?
          any/c
          collapsible-contract?
          any/c
          (or/c #f collapsible-contract?)))
 = #f
  collapsible-guard : (-> collapsible-contract? any/c any/c any/c)
   = 
(λ (cc v neg)
  (error
   "internal error: contract does not support `collapsible-guard`" cc))
Constructs a collapsible contract property from a merging function and a guard. The try-merge argument is similar to merge, but may return #f instead of a collapsible contract and may be specialized to a particular collapsible contract. The collapsible-guard argument should be specialized to the particular collapsible contract being implemented.

struct

(struct collapsible-ho/c (latest-blame missing-party latest-ctc))

  latest-blame : blame?
  missing-party : any/c
  latest-ctc : contract?
A common parent structure for collapsible contracts for higher-order values. The latest-blame field holds the blame object for the most recent contract attached. Similarly, the missing-party field holds the latest missing party passed to the contract. The latest-contract field stores the most recent contract attached to the value.

struct

(struct collapsible-leaf/c (proj-list
    contract-list
    blame-list
    missing-party-list))
  proj-list : (listof (-> any/c any/c any/c))
  contract-list : (listof contract?)
  blame-list : (listof blame?)
  missing-party-list : (listof any/c)
A structure representing the leaf nodes of a collapsible contract. The proj-list field holds a list of partially applied late neg projections. The contract-list, blame-list, and missing-party-list fields hold a list of contracts, blame objects, and blame missing parties respectively.

value

impersonator-prop:collapsible : impersonator-property?

procedure

(has-impersonator-prop:collapsible? v) → boolean?

  v : any/c

procedure

(get-impersonator-prop:collapsible v) → collapsible-property?

  v : any/c
An impersonator property (and its accessors) that should be attached to chaperoned or impersonated values that are guarded with a collapsible contract.

struct

(struct collapsible-property (c-c neg-party ref))

  c-c : collapsible-contract?
  neg-party : any/c
  ref : (or/c #f impersonator?)
The parent struct of properties that should be attached to chaperones or impersonators of values protected with a collapsible contract. The c-c field stores the collapsible contract that is or will in the future be attached to the the value. The neg-party field stores the latest missing blame party passed to the contract on the value. The ref field is mutable and stores a reference to the chaperone or impersonator to which this property is attached. This is necessary to determine whether an unknown chaperone has been attached to a value after it has been protected by a collapsible contract.

struct

(struct collapsible-count-property collapsible-property (count
    prev))
  count : natural-number/c
  prev : (or/c collapsible-count-property? any/c)
This property is associated with the impersonator-prop:collapsible property before the value completely enters the collapsible mode. These properties keep track of the number of contracts on a value in the count field, and hold a reference to the previous count property in the prev field or the original value without a contract. This allows the contract system to traverse the chain of attached contracts and merge them into a single collapsible contract to protect the original value.

struct

(struct collapsible-wrapper-property collapsible-property
  (checking-wrapper)
  checking-wrapper : impersonator?
This property is used when a value is guarded by a collapsible contract. The checking-wrapper field holds a chaperone or impersonator that dispatches to the collapsible contract stored in this property to perform any necessary contract checks. When the value receives another contract and merging happens, the checking wrapper will remain the same even though the specific collapsible contract attached to the value may change.

  top  contents  ← prev  up  next →