← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/core/leadership/interface.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/core/leadership/interface.go
 
1
// Copyright 2015 Canonical Ltd.
 
2
// Licensed under the AGPLv3, see LICENCE file for details.
 
3
 
 
4
/*
 
5
Package leadership holds code pertaining to application leadership in juju. It's
 
6
expected to grow as we're able to extract (e.g.) the Ticket and Tracker
 
7
interfaces from worker/leadership; and quite possible the implementations
 
8
themselves; but that'll have to wait until it can all be expressed without
 
9
reference to non-core code.
 
10
*/
 
11
package leadership
 
12
 
 
13
import (
 
14
        "time"
 
15
 
 
16
        "github.com/juju/errors"
 
17
)
 
18
 
 
19
// ErrClaimDenied is the error which will be returned when a
 
20
// leadership claim has been denied.
 
21
var ErrClaimDenied = errors.New("leadership claim denied")
 
22
 
 
23
// Claimer exposes leadership acquisition capabilities.
 
24
type Claimer interface {
 
25
 
 
26
        // ClaimLeadership claims leadership of the named application on behalf of the
 
27
        // named unit. If no error is returned, leadership will be guaranteed for
 
28
        // at least the supplied duration from the point when the call was made.
 
29
        ClaimLeadership(applicationId, unitId string, duration time.Duration) error
 
30
 
 
31
        // BlockUntilLeadershipReleased blocks until the named application is known
 
32
        // to have no leader, in which case it returns no error; or until the
 
33
        // manager is stopped, in which case it will fail.
 
34
        BlockUntilLeadershipReleased(applicationId string) (err error)
 
35
}
 
36
 
 
37
// Token represents a unit's leadership of its application.
 
38
type Token interface {
 
39
 
 
40
        // Check returns an error if the condition it embodies no longer holds.
 
41
        // If you pass a non-nil value into Check, it must be a pointer to data
 
42
        // of the correct type, into which the token's content will be copied.
 
43
        //
 
44
        // The "correct type" is implementation-specific, and no implementation
 
45
        // is obliged to accept any non-nil parameter; but methods that return
 
46
        // Tokens should explain whether, and how, they will expose their content.
 
47
        //
 
48
        // In practice, most Token implementations will likely expect *[]txn.Op,
 
49
        // so that they can be used to gate mgo/txn-based state changes.
 
50
        Check(interface{}) error
 
51
}
 
52
 
 
53
// Checker exposes leadership testing capabilities.
 
54
type Checker interface {
 
55
 
 
56
        // LeadershipCheck returns a Token representing the supplied unit's
 
57
        // application leadership. The existence of the token does not imply
 
58
        // its accuracy; you need to Check() it.
 
59
        //
 
60
        // This method returns a token that accepts a *[]txn.Op, into which
 
61
        // it will (on success) copy mgo/txn operations that can be used to
 
62
        // verify the unit's continued leadership as part of another txn.
 
63
        LeadershipCheck(applicationName, unitName string) Token
 
64
}
 
65
 
 
66
// Ticket is used to communicate leadership status to Tracker clients.
 
67
type Ticket interface {
 
68
 
 
69
        // Wait returns true if its Tracker is prepared to guarantee leadership
 
70
        // for some period from the ticket request. The guaranteed duration depends
 
71
        // upon the Tracker.
 
72
        Wait() bool
 
73
 
 
74
        // Ready returns a channel that will be closed when a result is available
 
75
        // to Wait(), and is helpful for clients that want to select rather than
 
76
        // block on long-waiting tickets.
 
77
        Ready() <-chan struct{}
 
78
}
 
79
 
 
80
// Tracker allows clients to discover current leadership status by attempting to
 
81
// claim it for themselves.
 
82
type Tracker interface {
 
83
 
 
84
        // ApplicationName returns the name of the application for which leadership claims
 
85
        // are made.
 
86
        ApplicationName() string
 
87
 
 
88
        // ClaimDuration returns the duration for which a Ticket's true Wait result
 
89
        // is guaranteed valid.
 
90
        ClaimDuration() time.Duration
 
91
 
 
92
        // ClaimLeader will return a Ticket which, when Wait()ed for, will return
 
93
        // true if leadership is guaranteed for at least the tracker's duration from
 
94
        // the time the ticket was issued. Leadership claims should be resolved
 
95
        // relatively quickly.
 
96
        ClaimLeader() Ticket
 
97
 
 
98
        // WaitLeader will return a Ticket which, when Wait()ed for, will block
 
99
        // until the tracker attains leadership.
 
100
        WaitLeader() Ticket
 
101
 
 
102
        // WaitMinion will return a Ticket which, when Wait()ed for, will block
 
103
        // until the tracker's future leadership can no longer be guaranteed.
 
104
        WaitMinion() Ticket
 
105
}