mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-02-01 18:01:23 -05:00
72 lines
2.7 KiB
Go
72 lines
2.7 KiB
Go
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
|
|
}
|