package pdsh

type (
	/*
		Generator is one of the PDSH host generators/iterators offered by this module.

		Note that these generators/iterators are *stateful*, which means they shouldn't
		(probably; I'm not your dad) be used concurrently (unless you want some hard-to-debug results)
		and all methods advance the generator - so you probably don't want to call both Generate() and
		Next()/Host() on the same instance, for example.
	*/
	Generator interface {
		/*
			Generate provides a Go-native iterator (also called a "RangeFunc" or "range over function type")
			as found in Go 1.23 onwards.

			See the assocaied blog entry for details: https://go.dev/blog/range-functions

			Essentially it allows for e.g.:

				for host := range (Generator).Generate() {
					// ...
				}

			which is the "new standard" approach for iteration.
		*/
		Generate() (yieldFunc func(yield func(host string) (done bool)))
		/*
			Reset is used to reset a Generator, allowing one to "restart" the generation at the beginning.

			Generators in this module are generally single-use, but can be reset/reused with this method.
		*/
		Reset()
		/*
			Hosts returns a complete generated hostlist at once if you'd rather not iterate.

			Hosts() *does* perform an iteration in runtime, so the recommendation against concurrency
			stands, but it calls Reset() when done generating to allow other methods of a Generator to be used.
		*/
		Hosts() (hostList []string)
		/*
			Next and Host behave like more "traditional" iterators, e.g. like (database/sql).Row.Next().

			Next advances the internal state to the next host, and Host() returns it.
		*/
		Next() (done bool)
		/*
			Host returns the current host string (or "" if done).

			Be sure to e.g.:

				for (Generator).Next() {
					host := (Generator).Host()
				}

			otherwise the Host return value will not change.
		*/
		Host() (host string)
	}
)