listener

Documentation

Overview

Package listener provides a way to incorporate graceful shutdown to any net.Listener.

This package provides low-level primitives, not a high-level API. If you're looking for a package that provides graceful shutdown for HTTP servers, I recommend this package's parent package, github.com/zenazn/goji/graceful.

Index

• Constants
• func Disown(c net.Conn) error
• func MarkIdle(c net.Conn) error
• func MarkInUse(c net.Conn) error
• type T
  • func Wrap(l net.Listener, m mode) *T
  • func (t *T) Accept() (net.Conn, error)
  • func (t *T) Addr() net.Addr
  • func (t *T) Close() error
  • func (t *T) CloseIdle() error
  • func (t *T) Drain() error

Constants

const (
	// Manual mode is completely manual: users must use use MarkIdle and
	// MarkInUse to indicate when connections are busy servicing requests or
	// are eligible for termination.
	Manual mode = iota
	// Automatic mode is what most users probably want: calling Read on a
	// connection will mark it as in use, but users must manually call
	// MarkIdle to indicate when connections may be safely closed.
	Automatic
	// Deadline mode is like automatic mode, except that calling
	// SetReadDeadline on a connection will also mark it as being idle. This
	// is useful for many servers like net/http, where SetReadDeadline is
	// used to implement read timeouts on new requests.
	Deadline
)

Functions

func Disown

func Disown(c net.Conn) error

Disown causes a connection to no longer be tracked by the listener. The passed connection must have been returned by a call to Accept from this listener.

func MarkIdle

func MarkIdle(c net.Conn) error

MarkIdle marks the given connection as being idle, and therefore eligible for closing at any time. The passed connection must have been returned by a call to Accept from this listener.

func MarkInUse

func MarkInUse(c net.Conn) error

MarkInUse marks this connection as being in use, removing it from the set of connections which are eligible for closing. The passed connection must have been returned by a call to Accept from this listener.

Types

type T

type T struct {
	// contains filtered or unexported fields
}

T is the type of this package's graceful listeners.

func Wrap

func Wrap(l net.Listener, m mode) *T

Wrap a net.Listener, returning a net.Listener which supports idle connection tracking and shutdown. Listeners can be placed in to one of three modes, exported as variables from this package: most users will probably want the "Automatic" mode.

func (*T) Accept

func (t *T) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener. The returned net.Conn's idleness is tracked, and idle connections can be closed from the associated T.

func (*T) Addr

func (t *T) Addr() net.Addr

Addr returns the wrapped listener's network address.

func (*T) Close

func (t *T) Close() error

Close closes the wrapped listener.

func (*T) CloseIdle

func (t *T) CloseIdle() error

CloseIdle closes all connections that are currently marked as being idle. It, however, makes no attempt to wait for in-use connections to die, or to close connections which become idle in the future. Call this function if you're interested in shedding useless connections, but otherwise wish to continue serving requests.

func (*T) Drain

func (t *T) Drain() error

Drain immediately closes all idle connections, prevents new connections from being accepted, and waits for all outstanding connections to finish.

Once a listener has been drained, there is no way to re-enable it. You probably want to Close the listener before draining it, otherwise new connections will be accepted and immediately closed.