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

     1  // Copyright 2017 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 fsm provides an interface for defining and working with finite-state
    13  machines.
    14  
    15  The package is split into two main types: Transitions and Machine. Transitions
    16  is an immutable State graph with Events acting as the directed edges between
    17  different States. The graph is built by calling Compile on a Pattern, which is
    18  meant to be done at init time. This pattern is a mapping from current States to
    19  Events that may be applied on those states to resulting Transitions. The pattern
    20  supports pattern matching on States and Events using wildcards and variable
    21  bindings. To add new transitions to the graph, simply adjust the Pattern
    22  provided to Compile. Transitions are not used directly after creation, instead,
    23  they're used by Machine instances.
    24  
    25  Machine is an instantiation of a finite-state machine. It is given a Transitions
    26  graph when it is created to specify its State graph. Since the Transition graph
    27  is itself state-less, multiple Machines can be powered by the same graph
    28  simultaneously. The Machine has an Apply(Event) method, which applies the
    29  provided event to its current state. This does two things:
    30  1. It may move the current State to a new State, according to the Transitions
    31     graph.
    32  2. It may apply an Action function on the Machine's ExtendedState, which is
    33     extra state in a Machine that does not contribute to state transition
    34     decisions, but that can be affected by a state transition.
    35  
    36  See example_test.go for a full working example of a state machine with an
    37  associated set of states and events.
    38  
    39  This package encourages the Pattern to be declared as a map literal. When
    40  declaring this literal, be careful to not declare two equal keys: they'll result
    41  in the second overwriting the first with no warning because of how Go deals with
    42  map literals. Note that keys that are not technically equal, but where one is a
    43  superset of the other, will work as intended. E.g. the following is permitted:
    44   Compile(Pattern{
    45     stateOpen{retryIntent: Any} {
    46       eventTxnFinish{}: {...}
    47     }
    48     stateOpen{retryIntent: True} {
    49       eventRetriableErr{}: {...}
    50     }
    51  
    52  Members of this package are accessed frequently when implementing a state
    53  machine. For that reason, it is encouraged to dot-import this package in the
    54  file with the transitions Pattern. The respective file should be kept small and
    55  named <name>_fsm.go; our linter doesn't complain about dot-imports in such
    56  files.
    57  
    58  */
    59  package fsm