github.com/m3db/m3@v1.5.0/src/cluster/services/leader/doc.go (about)

     1  // Copyright (c) 2017 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  /*
    22  Package leader provides functionality for etcd-backed leader elections.
    23  
    24  The following diagram illustrates the states of an election:
    25  
    26                           FOLLOWER<---------------+
    27                              +                    ^
    28                              |                    |
    29            Campaign() blocks +-------------------->
    30                              |     Resign()       |
    31                              |                    |
    32                              v                    |
    33                     +--------+                    |
    34                     |        |                    |
    35                     |        | Campaign() OK      |
    36                     |        |                    |
    37                     |        |                    |
    38     Campaign() Err  |        v      Resign()      |
    39                     |      LEADER+--------------->+
    40                     |        +                    ^
    41                     |        | Lose session       |
    42                     |        |                    |
    43                     |        v                    |
    44                     +----->ERROR+-----------------+
    45                                  Campaign() again
    46  
    47  An election starts in FOLLOWER state when a call to Campaign() is first made.
    48  The underlying call to etcd will block until the client is either (a) elected
    49  (in which case the election will be in LEADER state) or (b) an error is
    50  encountered (in which case election will be in ERROR state). If an election is
    51  in LEADER state but the session expires in the background it will transition to
    52  ERROR state (and Campaign() will need to be called again to progress). If an
    53  election is in LEADER state and the user calls Resign() it will transition back
    54  to FOLLOWER state. Finally, if an election is in FOLLOWER state and a blocking
    55  call to Campaign() is ongoing and the user calls Resign(), the campaign will be
    56  cancelled and the election back in FOLLOWER state.
    57  
    58  Callers of Campaign() MUST consume the returned channel until it is closed or
    59  risk goroutine leaks.
    60  */
    61  package leader