Top 7.0% dependent packages on proxy.golang.org
proxy.golang.org : github.com/shabbyrobe/go-service
Package service implements service-like goroutine lifecycle management. It is intended for use when you need to co-ordinate the state of one or more long-running goroutines and control startup and shutdown. Package service is complemented by the 'github.com/shabbyrobe/go-service/services' package, which provides a global version of a service.Runner for use in simpler applications. Quick Example Services are by nature heavier than a regular goroutine; they're up to 10x slower and use more memory. You should probably only use Services when you need to fully control the management of a long-lived goroutine, otherwise they're likely not worth it: There are plenty of opportunities for memory savings in the library, but the chief priority has been to get a working, stable and complete API first. I don't plan to start 50,000 services a second in any app I am currently working on, but this is not to say that optimising the library isn't important, it's just not a priority yet. YMMV. Runnables can be created by implementing the Runnable interface. This interface only contains one method (Run), but there are some very important caveats in order to correctly implement it: The Run() method will be run in the background by a Runner. The Run() method MUST do the following to be considered valid. Violating any of these rules will result in Undefined Behaviour (uh-oh!): ctx.Ready() MUST be called and error checked properly <-ctx.Done() MUST be included in any select {} block OR... ctx.ShouldHalt() MUST be checked frequently enough that your calls to Halt() won't time out if <-ctx.Done() is not used. If Run() ends before it is halted by a Runner, an error MUST be returned. If there is no obvious application specific error to return in this case, service.ErrServiceEnded MUST be returned. The Run() method SHOULD do the following: Here is an example of a Run() method which uses a select{} loop: Here is an example of a Run() method which sleeps: service.RunnableFunc allows you to use a bare function as a Runnable instead of implementing the Service interface: To start or halt a Runnable, a Runner is required and the Runnable must be wrapped in a service.Service: Service.Run receives a service.Context as its first parameter. service.Context implements context.Context (https://golang.org/pkg/context/). You should use the ctx as the basis for any child contexts you wish to create in your service, as you will then gain access to cancellation propagation from Runner.Halt(): The rules around when the ctx passed to Run() is considered Done() are different depending on whether ctx.Ready() has been called. If ctx.Ready() has not yet been called, the ctx passed to Run() is Done() if: If ctx.Ready() has been called, the ctx passed to Run() is Done() if: The context passed to Runner.Halt() is not bound to the ctx passed to Run(). The rationale for this decision is that if you need to do things in your service that require a context.Context after Run's ctx is Done() (i.e. when your Runnable is Halting), you are responsible for creating your own context: The guideline for this may change, but at the moment the best recommendation is to use context.Background() in this case: if you are calling Runner.Halt() and your context deadline runs out, you have lost resources no matter what. Runner takes a list of functional RunnerOptions that can be used to listen to events. The RunnerOnEnd option allows you to supply a callback which is executed when a service ends: OnEnd will always be called if a Runnable's Run() function returns, whether that is because the service failed prematurely or because it was halted. If the service has ended because it was halted, err will be nil. If the service has ended for any other reason, err MUST contain an error. The RunnerOnError option allows you to supply a callback which is executed when a service calls service.Context.OnError(err). Context.OnError(err) is used when an error occurs that cannot be handled and does not terminate the service. It's most useful for logging: You MUST NOT attempt to call your Runner from inside your OnEnd or OnError function. This will cause a deadlock. If you wish to call the runner, wrap your function body in an anonymous goroutine: All Runnable implementations are restartable by default. If written carefully, it's also possible to start the same Runnable in multiple Runners. Maybe that's not a good idea, but who am I to judge? You might have a great reason. Some Runnable implementations may wish to explicitly block restart, such as tings that wrap a net.Conn (which will not be available if the service fails). An atomic can be a good tool for this job:
Registry
-
Source
- Documentation
- JSON
purl: pkg:golang/github.com/shabbyrobe/go-service
License: MIT
Latest release: about 2 years ago
First release: over 4 years ago
Namespace: github.com/shabbyrobe
Dependent packages: 1
Stars: 6 on GitHub
Forks: 1 on GitHub
See more repository details: repos.ecosyste.ms
Last synced: 22 days ago