Documentation
¶
Overview ¶
Package graceful implements graceful shutdown for HTTP servers by closing idle connections after receiving a signal. By default, this package listens for interrupts (i.e., SIGINT), but when it detects that it is running under Einhorn it will additionally listen for SIGUSR2 as well, giving your application automatic support for graceful upgrades.
It's worth mentioning explicitly that this package is a hack to shim graceful shutdown behavior into the net/http package provided in Go 1.2. It was written by carefully reading the sequence of function calls net/http happened to use as of this writing and finding enough surface area with which to add appropriate behavior. There's a very good chance that this package will cease to work in future versions of Go, but with any luck the standard library will add support of its own by then (https://code.google.com/p/go/issues/detail?id=4674).
If you're interested in figuring out how this package works, we suggest you read the documentation for WrapConn() and net.go.
Index ¶
- func AddSignal(sig ...os.Signal)
- func HandleSignals()
- func ListenAndServe(addr string, handler http.Handler) error
- func ListenAndServeTLS(addr, certfile, keyfile string, handler http.Handler) error
- func Middleware(h http.Handler) http.Handler
- func PostHook(f func())
- func PreHook(f func())
- func ResetSignals()
- func Serve(l net.Listener, handler http.Handler) error
- func Shutdown()
- func Wait()
- func WrapConn(c net.Conn) net.Conn
- func WrapListener(l net.Listener) net.Listener
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddSignal ¶
AddSignal adds the given signal to the set of signals that trigger a graceful shutdown.
func HandleSignals ¶
func HandleSignals()
HandleSignals installs signal handlers for a set of standard signals. By default, this set only includes keyboard interrupts, however when the package detects that it is running under Einhorn, a SIGUSR2 handler is installed as well.
func ListenAndServe ¶
ListenAndServe behaves exactly like the net/http function of the same name.
func ListenAndServeTLS ¶
ListenAndServeTLS behaves exactly like the net/http function of the same name.
func Middleware ¶
Middleware is a stub that does nothing. When used with versions of Go before Go 1.3, it provides functionality similar to net/http.Server's SetKeepAlivesEnabled.
func PostHook ¶
func PostHook(f func())
PostHook registers a function to be called after all of this package's normal shutdown actions. All listeners will be called in the order they were added, from a single goroutine, and are guaranteed to be called after all listening connections have been closed, but before Wait() returns.
If you've Hijack()ed any connections that must be gracefully shut down in some other way (since this library disowns all hijacked connections), it's reasonable to use a PostHook() to signal and wait for them.
func PreHook ¶
func PreHook(f func())
PreHook registers a function to be called before any of this package's normal shutdown actions. All listeners will be called in the order they were added, from a single goroutine.
func ResetSignals ¶
func ResetSignals()
ResetSignals resets the list of signals that trigger a graceful shutdown.
func Shutdown ¶
func Shutdown()
Shutdown manually triggers a shutdown from your application. Like Wait(), blocks until all connections have gracefully shut down.
func Wait ¶
func Wait()
Wait for all connections to gracefully shut down. This is commonly called at the bottom of the main() function to prevent the program from exiting prematurely.
func WrapConn ¶
WrapConn wraps an arbitrary connection for use with graceful shutdowns. The graceful shutdown process will ensure that this connection is closed before terminating the process.
In order to use this function, you must call SetReadDeadline() before the call to Read() you might make to read a new request off the wire. The connection is eligible for abrupt closing at any point between when the call to SetReadDeadline() returns and when the call to Read returns with new data. It does not matter what deadline is given to SetReadDeadline()--if a deadline is inappropriate, providing one extremely far into the future will suffice.
Unfortunately, this means that it's difficult to use SetReadDeadline() in a great many perfectly reasonable circumstances, such as to extend a deadline after more data has been read, without the connection being eligible for "graceful" termination at an undesirable time. Since this package was written explicitly to target net/http, which does not as of this writing do any of this, fixing the semantics here does not seem especially urgent.
Types ¶
type Server ¶
Type Server is exactly the same as an http.Server, but provides more graceful implementations of its methods.
Source Files