← Back to branch summary

~nskaggs/+junk/juju-packaging-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/worker/fortress/interface.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-27 20:23:11 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161027202311-sux4jk2o73p1d6rg
Re-add src

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/worker/fortress/interface.go
 
1
// Copyright 2015 Canonical Ltd.
 
2
// Licensed under the AGPLv3, see LICENCE file for details.
 
3
 
 
4
/*
 
5
Package fortress implements a convenient metaphor for an RWLock.
 
6
 
 
7
A "fortress" is constructed via a manifold's Start func, and accessed via its
 
8
Output func as either a Guard or a Guest. To begin with, it's considered to be
 
9
locked, and inaccessible to Guests; when the Guard Unlocks it, the Guests can
 
10
Visit it until the Guard calls Lockdown. At that point, new Visits are blocked,
 
11
and existing Visits are allowed to complete; the Lockdown returns once all
 
12
Guests' Visits have completed.
 
13
 
 
14
The original motivating use case was for a component to mediate charm directory
 
15
access between the uniter and the metrics collector. The metrics collector must
 
16
be free to run its own independent hooks while the uniter is active; but metrics
 
17
hooks and charm upgrades cannot be allowed to tread on one another's toes.
 
18
*/
 
19
package fortress
 
20
 
 
21
import (
 
22
        "github.com/juju/errors"
 
23
)
 
24
 
 
25
// Guard manages Guest access to a fortress.
 
26
type Guard interface {
 
27
 
 
28
        // Unlock unblocks all Guest.Visit calls.
 
29
        Unlock() error
 
30
 
 
31
        // Lockdown blocks new Guest.Visit calls, and waits for existing calls to
 
32
        // complete; it will return ErrAborted if the supplied Abort is closed
 
33
        // before lockdown is complete. In this situation, the fortress will
 
34
        // remain closed to new visits, but may still be executing pre-existing
 
35
        // ones; you need to wait for a Lockdown to complete successfully before
 
36
        // you can infer exclusive access.
 
37
        Lockdown(Abort) error
 
38
}
 
39
 
 
40
// Guest allows clients to Visit a fortress when it's unlocked; that is, to
 
41
// get non-exclusive access to whatever resource is being protected for the
 
42
// duration of the supplied Visit func.
 
43
type Guest interface {
 
44
 
 
45
        // Visit waits until the fortress is unlocked, then runs the supplied
 
46
        // Visit func. It will return ErrAborted if the supplied Abort is closed
 
47
        // before the Visit is started.
 
48
        Visit(Visit, Abort) error
 
49
}
 
50
 
 
51
// Visit is an operation that can be performed by a Guest.
 
52
type Visit func() error
 
53
 
 
54
// Abort is a channel that can be closed to abort a blocking operation.
 
55
type Abort <-chan struct{}
 
56
 
 
57
// ErrAborted is used to confirm clean termination of a blocking operation.
 
58
var ErrAborted = errors.New("fortress operation aborted")