github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/util/interval/generic/doc.go (about)

     1  // Copyright 2020 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  /*
    12  Package generic provides an implementation of a generic immutable interval
    13  B-Tree.
    14  
    15  The package uses code generation to create type-safe, zero-allocation
    16  specializations of the ordered tree structure.
    17  
    18  Usage
    19  
    20  Users of the package should follow these steps:
    21  
    22    1. Define a type that will be used to parameterize the generic tree structure.
    23    2. Ensure that the parameter type fulfills the type contract defined in
    24       internal/contract.go.
    25    3. Include a go generate declaration that invokes the gen.sh script with the
    26       type name as the first argument and the package name as the second argument.
    27    4. Invoke go generate.
    28  
    29  Example
    30  
    31  1. The latch type is defined:
    32  
    33    type latch struct {
    34        id         uint64
    35        span       roachpb.Span
    36        ts         hlc.Timestamp
    37        done       *signal
    38        next, prev *latch // readSet linked-list.
    39    }
    40  
    41  2. Methods are defined to fulfill the type contract.
    42  
    43    func (la *latch) ID() uint64         { return la.id }
    44    func (la *latch) Key() []byte        { return la.span.Key }
    45    func (la *latch) EndKey() []byte     { return la.span.EndKey }
    46    func (la *latch) String() string     { return fmt.Sprintf("%s@%s", la.span, la.ts) }
    47    func (la *latch) SetID(v uint64)     { la.id = v }
    48    func (la *latch) SetKey(v []byte)    { la.span.Key = v }
    49    func (la *latch) SetEndKey(v []byte) { la.span.EndKey = v }
    50  
    51  3. The following comment is added near the declaration of the latch type:
    52  
    53    //go:generate ../../util/interval/generic/gen.sh *latch spanlatch
    54  
    55  4. Invoking go generate results in the creation of the following files:
    56  
    57    * latch_interval_btree.go
    58    * latch_interval_btree_test.go
    59  
    60  Working Example
    61  
    62  See example_t.go for a working example. Running go generate on this package
    63  generates:
    64    * example_interval_btree.go
    65    * example_interval_btree_test.go
    66  */
    67  package generic