README
¶
chanstream
Package chanstream implements an API compatible with and similiar to the TCP connection (and net.Conn as well) API, on top of Go channels. This is in pure Go, without any external dependencies.
The intention is to facilitate the use of channels for intra-program communication, in a manner similiar to TCP or Unix Domain sockets, without creating any externally visible addresses or service points. (This can also be done more efficiently, since data need not be copied to the kernel.)
An observer might wonder why not just utilize Go channels directly? The rationale here is that this allows abstraction layers to be built on top of channels that can choose to use channels (via chanstream) or TCP or other transports. This can make it possible to eliminate certain special cases in program handling.
In particular, this package was developed to support an effort to produce a pure Go implementation of nanomsg and/or ZeroMQ. This package can be used as the underlying transport for the inproc: scheme.
Consider this a work-in-progress, and use at your own risk.
Installing
Using go get
$ go get github.com/gdamore/chanstream
After this command chanstream is ready to use. Its source will be in:
$GOROOT/src/pkg/github.com/gdamore/chanstream
You can use go get -u -a to update all installed packages.
Documentation
For docs, see http://godoc.org/github.com/gdamore/chanstream or run:
$ go doc github.com/gdamore/chanstream
Copyright 2015 Garrett D'Amore garrett@damore.org
Documentation
¶
Overview ¶
Package chanstream provides an API that is similar to that used for TCP and Unix Domain sockets (see net.TCP), for use in intra-process communication on top of Go channels. This makes it easy to swap it for another net.Conn interface.
By using channels, we avoid exposing any interface to other processors, or involving the kernel to perform data copying.
Index ¶
- Variables
- type ChanAddr
- type ChanConn
- func (conn *ChanConn) Close() error
- func (conn *ChanConn) CloseRead() error
- func (conn *ChanConn) CloseWrite() error
- func (conn *ChanConn) LocalAddr() net.Addr
- func (conn *ChanConn) Read(b []byte) (int, error)
- func (conn *ChanConn) RemoteAddr() net.Addr
- func (conn *ChanConn) SetDeadline(t time.Time) error
- func (conn *ChanConn) SetReadDeadline(t time.Time) error
- func (conn *ChanConn) SetWriteDeadline(t time.Time) error
- func (conn *ChanConn) Write(b []byte) (int, error)
- type ChanError
- type ChanListener
Constants ¶
This section is empty.
Variables ¶
var ( // ErrConnRefused is reported when no listener is present and // a client attempts to connect via Dial. ErrConnRefused = &ChanError{err: "Connection refused."} // ErrAddrInUse is reported when a server tries to Listen but another // Conn is already listening on the same address. ErrAddrInUse = &ChanError{err: "Address in use."} // ErrAcceptTimeout is reported when a request to Accept takes too // long. (Note that this is not normally reported -- the default // is for no timeout to be used in Accept.) ErrAcceptTimeout = &ChanError{err: "Accept timeout.", tmo: true} // ErrListenQFull is reported if the listen backlog (default 32) // is exhausted. This normally occurs if a server goroutine does // not call Accept often enough. ErrListenQFull = &ChanError{err: "Listen queue full.", tmp: true} // ErrConnClosed is reported when a peer closes the connection while // trying to establish the connection or send data. ErrConnClosed = &ChanError{err: "Connection closed."} // ErrConnTimeout is reported when a connection takes too long to // be established. ErrConnTimeout = &ChanError{err: "Connection timeout.", tmo: true} // ErrRdTimeout is reported when the read deadline on a connection // expires whle trying to read. ErrRdTimeout = &ChanError{err: "Read timeout.", tmo: true, tmp: true} // ErrWrTimeout is reported when the write deadline on a connection // expires whle trying to write. ErrWrTimeout = &ChanError{err: "Write timeout.", tmo: true, tmp: true} )
Functions ¶
This section is empty.
Types ¶
type ChanAddr ¶
type ChanAddr struct {
// contains filtered or unexported fields
}
ChanAddr stores just the address, which will normally be something like a path, but any valid string can be used as a key. This implements the net.Addr interface.
type ChanConn ¶
type ChanConn struct {
// contains filtered or unexported fields
}
ChanConn represents a logical connection between two peers communication using a pair of cross-connected go channels. This provides net.Conn semantics on top of channels.
func (*ChanConn) Close ¶
Close implements the io.Closer interface. It closes the channel for communications. Messages that have already been sent may be received by the peer before the peer closes its side of the connection. A notification is sent to the peer so it will close its side as well.
func (*ChanConn) CloseRead ¶
CloseRead closes the read side of the connection. Addtionally, a notification is sent to the peer, to begin an orderly shutdown of the connection. No further data may be read from the connection.
func (*ChanConn) CloseWrite ¶
CloseWrite closes the write side of the channel. After this point, it is illegal to write data on the connection.
func (*ChanConn) LocalAddr ¶
LocalAddr returns the local address. For now, both client and server use the same address, which is the key used for Listen or Dial.
func (*ChanConn) RemoteAddr ¶
RemoteAddr returns the peer's address. For now, both client and server use the same address, which is the key used for Listen or Dial.
func (*ChanConn) SetDeadline ¶
SetDeadline sets the timeout for both read and write.
func (*ChanConn) SetReadDeadline ¶
SetReadDeadline sets the timeout for read (receive).
func (*ChanConn) SetWriteDeadline ¶
SetWriteDeadline sets the timeout for write (send).
type ChanError ¶
type ChanError struct {
// contains filtered or unexported fields
}
ChanError implements the error and net.Error interfaces.
type ChanListener ¶
type ChanListener struct {
// contains filtered or unexported fields
}
ChanListener is used to listen to a socket.
func ListenChan ¶
func ListenChan(name string) (*ChanListener, error)
ListenChan establishes the server address and receiving channel where clients can connect. This service address is backed by a go channel.
func (*ChanListener) Accept ¶
func (listener *ChanListener) Accept() (net.Conn, error)
Accept is a generic way to accept a connection.
func (*ChanListener) AcceptChan ¶
func (listener *ChanListener) AcceptChan() (*ChanConn, error)
AcceptChan accepts a client's connection request via Dial, and returns the associated underlying connection.
Source Files