drain

type Cancel struct {
	Drainer Interface
}

type Interface interface {
	// Start attempts to begin draining devices.  The supplied Job describes how the drain will proceed.
	// The returned channel can be used to wait for the drain job to complete.  The returned Job will be
	// the result of applying defaults and will represent the actual Job being executed.  For example, if Job.Rate
	// is set but Job.Tick is not, the returned Job will reflect the default of 1 second for Job.Tick.
	Start(Job) (<-chan struct{}, Job, error)

	// Status returns information about the current drain job, if any.  The boolean return indicates whether
	// the job is currently active, while the returned Job describes the actual options used in starting the drainer.
	// This returned Job instance will not necessarily be the same as that passed to Start, as certain fields
	// may be computed or defaulted.
	Status() (bool, Job, Progress)

	// Cancel asynchronously halts any running drain job.  The returned channel can be used to wait for the job to actually exit.
	// If no job is running, an error is returned along with a nil channel.
	Cancel() (<-chan struct{}, error)
}

type Job struct {
	// Count is the total number of devices to disconnect.  If this field is nonpositive and percent is unset,
	// the count of connected devices at the start of job execution is used.  If Percent is set, this field's
	// original value is ignored and it is set to that percentage of total devices connected at the time the
	// job starts.
	Count int `json:"count" schema:"count"`

	// Percent is the fraction of devices to drain.  If this field is set, Count's original value is ignored
	// and set to the computed percentage of connected devices at the time the job starts.
	Percent int `json:"percent,omitempty" schema:"percent"`

	// Rate is the number of devices per tick to disconnect.  If this field is nonpositive,
	// devices are disconnected as fast as possible.
	Rate int `json:"rate,omitempty" schema:"rate"`

	// Tick is the time unit for the Rate field.  If Rate is set but this field is not set,
	// a tick of 1 second is used as the default.
	Tick time.Duration `json:"tick,omitempty" schema:"tick"`
}

type Option func(*drainer)

type Progress struct {
	// Visited is the number of devices handled so far.  This value will not
	// exceed the Job.Count value.
	Visited int `json:"visited"`

	// Drained is the count of visited devices that have actually been disconnected
	// due to the drain.  Devices can disconnect or be disconnected outside a drain job,
	// so this value can be lower than Visited, even in a job that has finished.
	Drained int `json:"drained"`

	// Started is the UTC system time at which the drain job was started.
	Started time.Time `json:"started"`

	// Finished is the UTC system time at which the drain job finished or was canceled.
	// If the job is running, this field will be nil.
	Finished *time.Time `json:"finished,omitempty"`
}

type Start struct {
	Drainer Interface
}

type Status struct {
	Drainer Interface
}