Initial QSfera import

Server/vendor/github.com/thejerf/suture/v4/service.go

@@ -0,0 +1,71 @@
+package suture
+
+import (
+	"context"
+)
+
+/*
+Service is the interface that describes a service to a Supervisor.
+
+Serve Method
+
+The Serve method is called by a Supervisor to start the service.
+The service should execute within the goroutine that this is
+called in, that is, it should not spawn a "worker" goroutine.
+If this function either returns error or panics, the Supervisor
+will call it again.
+
+A Serve method SHOULD do as much cleanup of the state as possible,
+to prevent any corruption in the previous state from crashing the
+service again. The beginning of a service with persistent state should
+generally be a few lines to initialize and clean up that state.
+
+The error returned by the service, if any, will be part of the log
+message generated for it. There are two distinguished errors a
+Service can return:
+
+ErrDoNotRestart indicates that the service should
+not be restarted and removed from the supervisor entirely.
+
+ErrTerminateTree indicates that the Supervisor the service is running
+in should be terminated. If that Supervisor recursively returns that,
+its parent supervisor will also be terminated. (This can be controlled
+with configuration in the Supervisor.)
+
+In Go 1.13 and greater, this is checked via errors.Is, so the error
+can be further wrapped with whatever additional info you like. Prior
+to Go 1.13, it will be checked via directly equality check, so the
+distinguished errors cannot be wrapped.
+
+Once the service has been instructed to stop, the Service SHOULD NOT be
+reused in any other supervisor! Because of the impossibility of
+guaranteeing that the service has fully stopped in Go, you can't
+prove that you won't be starting two goroutines using the exact
+same memory to store state, causing completely unpredictable behavior.
+
+Serve should not return until the service has actually stopped.
+"Stopped" here is defined as "the service will stop servicing any
+further requests in the future". Any mandatory cleanup related to
+the Service should also have been performed.
+
+If a service does not stop within the supervisor's timeout duration, the
+supervisor will log an entry to that effect. This does
+not guarantee that the service is hung; it may still get around to being
+properly stopped in the future. Until the service is fully stopped,
+both the service and the spawned goroutine trying to stop it will be
+"leaked".
+
+Stringer Interface
+
+When a Service is added to a Supervisor, the Supervisor will create a
+string representation of that service used for logging.
+
+If you implement the fmt.Stringer interface, that will be used.
+
+If you do not implement the fmt.Stringer interface, a default
+fmt.Sprintf("%#v") will be used.
+
+*/
+type Service interface {
+	Serve(ctx context.Context) error
+}