Documentation ¶
Overview ¶
Package graceful provides tools for passing file descriptors between the applications.
It is intended to make graceful restarts of Go applications easier.
The very common example is:
ln, err := net.Listen("tcp", "localhost:") if err != nil { // handle error } ... // Work until must restart. // Open a server that shares given listener with each accepted connection. graceful.ListenAndServe( "/var/my_app/graceful.sock", graceful.ListenerHandler(ln), )
Index ¶
- Variables
- func FdConn(fd int) (net.Conn, error)
- func FdListener(fd int) (net.Listener, error)
- func FdPacketConn(fd int) (net.PacketConn, error)
- func ListenAndServe(addr string, handler Handler) error
- func Receive(addr string, cb ReceiveCallback) error
- func ReceiveAllFrom(conn net.Conn, cb ReceiveCallback) error
- func ReceiveFrom(conn net.Conn, cb ReceiveCallback) error
- func Send(addr string, fd int, meta io.WriterTo) error
- func SendConn(resp ResponseWriter, conn net.Conn, meta io.WriterTo) error
- func SendConnTo(dst, conn net.Conn, meta io.WriterTo) error
- func SendFile(resp ResponseWriter, file *os.File, meta io.WriterTo) error
- func SendFileTo(conn net.Conn, file *os.File, meta io.WriterTo) error
- func SendListener(resp ResponseWriter, ln net.Listener, meta io.WriterTo) error
- func SendListenerTo(conn net.Conn, ln net.Listener, meta io.WriterTo) error
- func SendPacketConn(resp ResponseWriter, conn net.PacketConn, meta io.WriterTo) error
- func SendTo(conn net.Conn, fd int, meta io.WriterTo) error
- func Serve(ln net.Listener, handler Handler) error
- type CallbackHandler
- type Client
- type DebugLogger
- type ErrorLogger
- type Handler
- func ConnHandler(conn net.Conn, meta io.WriterTo) Handler
- func FdHandler(fd int, meta io.WriterTo) Handler
- func FileHandler(file *os.File, meta io.WriterTo) Handler
- func ListenerHandler(ln net.Listener, meta io.WriterTo) Handler
- func PacketConnHandler(conn net.PacketConn, meta io.WriterTo) Handler
- func SequenceHandler(hs ...Handler) Handler
- type HandlerFunc
- type InfoLogger
- type Logger
- type Meta
- type ReceiveCallback
- type ResponseWriter
- type Server
- func (s *Server) ListenAndServe(addr string) error
- func (s *Server) SendConnTo(dst, conn net.Conn, meta io.WriterTo) error
- func (s *Server) SendFileTo(conn net.Conn, file *os.File, meta io.WriterTo) error
- func (s *Server) SendListenerTo(conn net.Conn, ln net.Listener, meta io.WriterTo) error
- func (s *Server) SendTo(conn net.Conn, fd int, meta io.WriterTo) error
- func (s *Server) Serve(l net.Listener) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrEmptyControlMessage = fmt.Errorf("empty control message") ErrEmptyFileDescriptors = fmt.Errorf("empty file descriptors") )
Errors used by Receive() function.
var ( // ErrNotUnixListener is returned by a Server when not a *net.UnixListener // is passed to its Serve() method. ErrNotUnixListener = errors.New("not a unix listener") // ErrLongWrite is returned by the ResponseWriter or Send* functions when // data that want be written is too large to be buffered. // // In this case user should send data separately to the client. // // Note that it is not possible to send messages larger than selected // buffer size because client still will not receive it due to that client // and server must use the same buffer size for reading and writing. ErrLongWrite = errors.New("long write") )
Errors used by the Server and server helpers.
var ErrNotFiler = fmt.Errorf("given value does not provide *os.File getter")
ErrNotFiler returned when object given to Send* functios does provides ability for getting its underlying *os.File.
var ErrNotUnixConn = errors.New("not a unix connection")
ErrNotUnixConn is returned by a Client when not a *net.UnixConn is passed to its Receive* methods.
Functions ¶
func FdConn ¶
FdConn is a helper function that converts given descriptor to the net.Conn interface.
func FdListener ¶
FdListener is a helper function that converts given descriptor to the net.Listener interface.
func FdPacketConn ¶
func FdPacketConn(fd int) (net.PacketConn, error)
FdPacketConn is a helper function that converts given descriptor to the net.PacketConn interface.
func ListenAndServe ¶
ListenAndServe creates Server instance with given handler and then calls server.ListenAndServe(addr) to handle incoming connections.
func Receive ¶
func Receive(addr string, cb ReceiveCallback) error
Receive dials to the "unix" network address addr and calls cb for each received descriptor from it until EOF.
func ReceiveAllFrom ¶
func ReceiveAllFrom(conn net.Conn, cb ReceiveCallback) error
ReceiveAllFrom reads all control messages from the given connection conn and calls cb for each descriptor inside those messages.
func ReceiveFrom ¶
func ReceiveFrom(conn net.Conn, cb ReceiveCallback) error
ReceiveFrom reads a single control message from the given connection conn and calls cb for each descriptor inside that message.
func SendConnTo ¶
SendConnTo sends connection conn and its meta to the given connection dst.
func SendFileTo ¶
SendFileTo sends file and its meta to the given conn.
func SendListener ¶
SendListener sends a listener ln with given meta to the ResponseWriter.
func SendListenerTo ¶
SendListenerTo sends listener ln and its meta to the given conn.
func SendPacketConn ¶
func SendPacketConn(resp ResponseWriter, conn net.PacketConn, meta io.WriterTo) error
SendPacketConn sends a connection conn with given meta to the ResponseWriter.
Types ¶
type CallbackHandler ¶
type CallbackHandler func()
HandlerFunc is an adapter to allow the use of ordinary functions with empty arguments as Handlers.
func (CallbackHandler) Handle ¶
func (cb CallbackHandler) Handle(net.Conn, ResponseWriter)
Handle calls cb().
type Client ¶
type Client struct {
// MsgBufferSize and OOBBufferSize defines an inner buffer sizes.
//
// MsgBufferSize defines size of the buffer for meta fields.
// If MsgBufferSize is zero, then the default size is used.
//
// OOBBufferSize defines size of the buffer for serialized descriptors.
// If OOBBufferSize is zero, then the default size is used.
//
// Note that client and server using this package MUST select the same
// buffer sizes. Another option is to use the global functions which use
// default sizes under the hood.
MsgBufferSize, OOBBufferSize int
// contains filtered or unexported fields
}
Client contains logic of parsing control messages.
func (*Client) Receive ¶
func (c *Client) Receive(addr string, cb ReceiveCallback) error
Receive dials to the "unix" network address addr and calls cb for each received descriptor.
func (*Client) ReceiveAllFrom ¶
func (c *Client) ReceiveAllFrom(conn net.Conn, cb ReceiveCallback) error
ReceiveAllFrom reads all control messages from the given connection conn and calls cb for each descriptor inside those messages.
func (*Client) ReceiveFrom ¶
func (c *Client) ReceiveFrom(conn net.Conn, cb ReceiveCallback) error
ReceiveFrom reads a single control message from the given connection conn and calls cb for each descriptor inside that message.
type DebugLogger ¶
type DebugLogger interface {
Debugf(string, ...interface{})
}
DebugLogger interface is used by a Sever or a Client to log some debug information.
type ErrorLogger ¶
type ErrorLogger interface {
Errorf(string, ...interface{})
}
ErrorLogger interface is used by a Sever or a Client to log some error information.
type Handler ¶
type Handler interface {
Handle(net.Conn, ResponseWriter)
}
Handler describes an object that can send descriptors to the connection with given ResponseWriter.
func ConnHandler ¶
ConnHandler returns a Handler that sends conn with given meta to the received connection. If some error occures, it logs it by calling resp.Errorf().
func FdHandler ¶
FdHandler returns a Handler that sends file descriptor with given meta to the received connection. If some error occures, it logs it by calling resp.Errorf().
func FileHandler ¶
FileHandler returns a Handler that sends file with given meta to the received connection. If some error occures, it logs it by calling resp.Errorf().
func ListenerHandler ¶
ListenerHandler returns a Handler that sends listener ln with given meta to the received connection. If some error occures, it logs it by calling resp.Errorf().
func PacketConnHandler ¶
func PacketConnHandler(conn net.PacketConn, meta io.WriterTo) Handler
PacketConnHandler returns a Handler that sends conn with given meta to the received connection. If some error occures, it logs it by calling resp.Errorf().
func SequenceHandler ¶
SequenceHandler returns a Handler that calls Handle() method on each passed handlers in sequence.
type HandlerFunc ¶
type HandlerFunc func(net.Conn, ResponseWriter)
HandlerFunc is an adapter to allow the use of ordinary functions as Handlers.
func (HandlerFunc) Handle ¶
func (h HandlerFunc) Handle(conn net.Conn, resp ResponseWriter)
Handle calls h(conn, resp).
type InfoLogger ¶
type InfoLogger interface {
Infof(string, ...interface{})
}
InfoLogger interface is used by a Sever or a Client to log some info information.
type Logger ¶
type Logger interface { DebugLogger InfoLogger ErrorLogger }
Logger interface is used by a ResponseWriter to provide log methods for Handlers.
func LoggerFunc ¶
LoggerFunc creates Logger from given functions.
type Meta ¶
type Meta map[string]interface{}
Meta is a helper type that is marshaled/unmarshaled by `endoding/gob` package and could be used as an additional information for a descriptor.
type ReceiveCallback ¶
ReceiveCallback describes a function that will be called on each received descriptor while parsing control messages. Its first argument is a received file descriptor. Its second argument is an optional meta information represented by an io.Reader.
If the callback returns non-nil error, then the function to which this callback was given exits immediately with that error.
Note that meta reader is only valid until callback returns. If server does not provide additional information for descriptor, meta argument will be nil.
type ResponseWriter ¶
type ResponseWriter interface { Logger // Write prepares file descriptor fd to be sent as well as an optional meta // information represented by an io.WriterTo. Write(fd int, meta io.WriterTo) error }
ResponseWriter describes an object that can receive a descriptor.
type Server ¶
type Server struct { // MsgBufferSize defines size of the buffer for meta fields. // If MsgBufferSize is zero, then the default size is used. MsgBufferSize int // OOBBufferSize defines size of the buffer for serialized descriptors. // If OOBBufferSize is zero, then the default size is used. OOBBufferSize int // Handler is a neccessary field that contains logic of sending descriptors // to the every arrived connection. Handler Handler // Logger contains optional implementation of any *Logger interfaces // provided by this package. // If Logger is nil, then no logging is made. Logger interface{} }
Server sends descriptors by calling Handler's Hanlde() method for every accepted connection.
Note that client and server using this package MUST select the same buffer sizes for the meta fields and descriptors. Another option is to use the global functions which use default sizes under the hood.
var DefaultServer Server
DefaultServer is an empty Server that is used by a Send* global functions as a method receiver.
func (*Server) ListenAndServe ¶
ListenAndServe listens on the "unix" network address addr and then calls Serve to handle incoming connections.
func (*Server) SendConnTo ¶
SendConnTo sends connection conn and its meta to the given connection dst.
func (*Server) SendFileTo ¶
SendFileTo sends file and its meta to the given conn.
func (*Server) SendListenerTo ¶
SendListenerTo sends listener ln and its meta to the given conn.