juju: github.com/juju/juju/worker/fortress Index | Files

package fortress

import "github.com/juju/juju/worker/fortress"

Package fortress implements a convenient metaphor for an RWLock.

A "fortress" is constructed via a manifold's Start func, and accessed via its Output func as either a Guard or a Guest. To begin with, it's considered to be locked, and inaccessible to Guests; when the Guard Unlocks it, the Guests can Visit it until the Guard calls Lockdown. At that point, new Visits are blocked, and existing Visits are allowed to complete; the Lockdown returns once all Guests' Visits have completed.

The original motivating use case was for a component to mediate charm directory access between the uniter and the metrics collector. The metrics collector must be free to run its own independent hooks while the uniter is active; but metrics hooks and charm upgrades cannot be allowed to tread on one another's toes.

Index

Package Files

fortress.go interface.go manifold.go occupy.go

Variables

var ErrAborted = errors.New("fortress operation aborted")

ErrAborted is used to confirm clean termination of a blocking operation.

var ErrShutdown = errors.New("fortress worker shutting down")

ErrShutdown is used to report that the fortress worker is shutting down.

func IsFortressError Uses

func IsFortressError(err error) bool

IsFortressError returns true if the error provided is fortress related.

func Manifold Uses

func Manifold() dependency.Manifold

Manifold returns a dependency.Manifold that runs a fortress.

Clients should access the fortress resource via Guard and/or Guest pointers. Guest.Visit calls will block until a Guard.Unlock call is made; Guard.Lockdown calls will block new Guest.Visits and wait until all active Visits complete.

If multiple clients act as guards, the fortress' state at any time will be determined by whichever guard last ran an operation; that is to say, it will be impossible to reliably tell from outside. So please don't do that.

func Occupy Uses

func Occupy(fortress Guest, start StartFunc, abort Abort) (worker.Worker, error)

Occupy launches a Visit to fortress that creates a worker and holds the visit open until the worker completes. Like most funcs that return any Worker, the caller takes responsibility for its lifetime; be aware that the responsibility is especially heavy here, because failure to clean up the worker will block cleanup of the fortress.

This may sound scary, but the alternative is to have multiple components "responsible for" a single worker's lifetime -- and Fortress itself would have to grow new concerns, of understanding and managing worker.Workers -- and that scenario ends up much worse.

type Abort Uses

type Abort <-chan struct{}

Abort is a channel that can be closed to abort a blocking operation.

type Guard Uses

type Guard interface {

    // Unlock unblocks all Guest.Visit calls.
    Unlock() error

    // Lockdown blocks new Guest.Visit calls, and waits for existing calls to
    // complete; it will return ErrAborted if the supplied Abort is closed
    // before lockdown is complete. In this situation, the fortress will
    // remain closed to new visits, but may still be executing pre-existing
    // ones; you need to wait for a Lockdown to complete successfully before
    // you can infer exclusive access.
    Lockdown(Abort) error
}

Guard manages Guest access to a fortress.

type Guest Uses

type Guest interface {

    // Visit waits until the fortress is unlocked, then runs the supplied
    // Visit func. It will return ErrAborted if the supplied Abort is closed
    // before the Visit is started.
    Visit(Visit, Abort) error
}

Guest allows clients to Visit a fortress when it's unlocked; that is, to get non-exclusive access to whatever resource is being protected for the duration of the supplied Visit func.

type StartFunc Uses

type StartFunc func() (worker.Worker, error)

StartFunc starts a worker.Worker.

type Visit Uses

type Visit func() error

Visit is an operation that can be performed by a Guest.

Package fortress imports 5 packages (graph) and is imported by 182 packages. Updated 2018-08-19. Refresh now. Tools for package owners.