5
0
mirror of https://github.com/cwinfo/yggdrasil-go.git synced 2024-11-10 04:00:37 +00:00

Update conn.go godoc

This commit is contained in:
Neil Alexander 2019-09-01 23:33:51 +01:00
parent 9e8e1c5a41
commit 935324efe1
No known key found for this signature in database
GPG Key ID: A02A2019A2BB0944

View File

@ -53,6 +53,9 @@ func (e *ConnError) Closed() bool {
return e.closed return e.closed
} }
// The Conn struct is a reference to an active connection session between the
// local node and a remote node. Conn implements the io.ReadWriteCloser
// interface and is used to send and receive traffic with a remote node.
type Conn struct { type Conn struct {
phony.Inbox phony.Inbox
core *Core core *Core
@ -78,6 +81,11 @@ func newConn(core *Core, nodeID *crypto.NodeID, nodeMask *crypto.NodeID, session
return &conn return &conn
} }
// String returns a string that uniquely identifies a connection. Currently this
// takes a form similar to "conn=0x0000000", which contains a memory reference
// to the Conn object. While this value should always be unique for each Conn
// object, the format of this is not strictly defined and may change in the
// future.
func (c *Conn) String() string { func (c *Conn) String() string {
var s string var s string
phony.Block(c, func() { s = fmt.Sprintf("conn=%p", c) }) phony.Block(c, func() { s = fmt.Sprintf("conn=%p", c) })
@ -159,7 +167,12 @@ func (c *Conn) _getDeadlineCancellation(t *time.Time) (util.Cancellation, bool)
} }
} }
// SetReadCallback sets a callback which will be called whenever a packet is received. // SetReadCallback allows you to specify a function that will be called whenever
// a packet is received. This should be used if you wish to implement
// asynchronous patterns for receiving data from the remote node.
//
// Note that if a read callback has been supplied, you should no longer attempt
// to use the synchronous Read function.
func (c *Conn) SetReadCallback(callback func([]byte)) { func (c *Conn) SetReadCallback(callback func([]byte)) {
c.Act(nil, func() { c.Act(nil, func() {
c.readCallback = callback c.readCallback = callback
@ -214,7 +227,14 @@ func (c *Conn) readNoCopy() ([]byte, error) {
} }
} }
// Implements net.Conn.Read // Read allows you to read from the connection in a synchronous fashion. The
// function will block up until the point that either new data is available, the
// connection has been closed or the read deadline has been reached. If the
// function succeeds, the number of bytes read from the connection will be
// returned. Otherwise, an error condition will be returned.
//
// Note that you can also implement asynchronous reads by using SetReadCallback.
// If you do that, you should no longer attempt to use the Read function.
func (c *Conn) Read(b []byte) (int, error) { func (c *Conn) Read(b []byte) (int, error) {
bs, err := c.readNoCopy() bs, err := c.readNoCopy()
if err != nil { if err != nil {
@ -256,9 +276,9 @@ func (c *Conn) _write(msg FlowKeyMessage) error {
return nil return nil
} }
// WriteFrom should be called by a phony.Actor, and tells the Conn to send a message. // WriteFrom should be called by a phony.Actor, and tells the Conn to send a
// This is used internaly by Write. // message. This is used internaly by Write. If the callback is called with a
// If the callback is called with a non-nil value, then it is safe to reuse the argument FlowKeyMessage. // non-nil value, then it is safe to reuse the argument FlowKeyMessage.
func (c *Conn) WriteFrom(from phony.Actor, msg FlowKeyMessage, callback func(error)) { func (c *Conn) WriteFrom(from phony.Actor, msg FlowKeyMessage, callback func(error)) {
c.Act(from, func() { c.Act(from, func() {
callback(c._write(msg)) callback(c._write(msg))
@ -288,7 +308,11 @@ func (c *Conn) writeNoCopy(msg FlowKeyMessage) error {
return err return err
} }
// Write implement the Write function of a net.Conn, and makes use of WriteNoCopy under the hood. // Write allows you to write to the connection in a synchronous fashion. This
// function may block until either the write has completed, the connection has
// been closed or the write deadline has been reached. If the function succeeds,
// the number of written bytes is returned. Otherwise, an error condition is
// returned.
func (c *Conn) Write(b []byte) (int, error) { func (c *Conn) Write(b []byte) (int, error) {
written := len(b) written := len(b)
msg := FlowKeyMessage{Message: append(util.GetBytes(), b...)} msg := FlowKeyMessage{Message: append(util.GetBytes(), b...)}
@ -300,6 +324,10 @@ func (c *Conn) Write(b []byte) (int, error) {
return written, err return written, err
} }
// Close will close an open connection and any blocking operations on the
// connection will unblock and return. From this point forward, the connection
// can no longer be used and you should no longer attempt to Read or Write to
// the connection.
func (c *Conn) Close() (err error) { func (c *Conn) Close() (err error) {
phony.Block(c, func() { phony.Block(c, func() {
if c.session != nil { if c.session != nil {
@ -314,10 +342,13 @@ func (c *Conn) Close() (err error) {
return return
} }
// LocalAddr returns the complete node ID of the local side of the connection.
// This is always going to return your own node's node ID.
func (c *Conn) LocalAddr() crypto.NodeID { func (c *Conn) LocalAddr() crypto.NodeID {
return *crypto.GetNodeID(&c.core.boxPub) return *crypto.GetNodeID(&c.core.boxPub)
} }
// RemoteAddr returns the complete node ID of the remote side of the connection.
func (c *Conn) RemoteAddr() crypto.NodeID { func (c *Conn) RemoteAddr() crypto.NodeID {
// TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors... // TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors...
var n crypto.NodeID var n crypto.NodeID
@ -325,18 +356,32 @@ func (c *Conn) RemoteAddr() crypto.NodeID {
return n return n
} }
// SetDeadline is equivalent to calling both SetReadDeadline and
// SetWriteDeadline with the same value, configuring the maximum amount of time
// that synchronous Read and Write operations can block for. If no deadline is
// configured, Read and Write operations can potentially block indefinitely.
func (c *Conn) SetDeadline(t time.Time) error { func (c *Conn) SetDeadline(t time.Time) error {
c.SetReadDeadline(t) c.SetReadDeadline(t)
c.SetWriteDeadline(t) c.SetWriteDeadline(t)
return nil return nil
} }
// SetReadDeadline configures the maximum amount of time that a synchronous Read
// operation can block for. A Read operation will unblock at the point that the
// read deadline is reached if no other condition (such as data arrival or
// connection closure) happens first. If no deadline is configured, Read
// operations can potentially block indefinitely.
func (c *Conn) SetReadDeadline(t time.Time) error { func (c *Conn) SetReadDeadline(t time.Time) error {
// TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors... // TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors...
phony.Block(c, func() { c.readDeadline = &t }) phony.Block(c, func() { c.readDeadline = &t })
return nil return nil
} }
// SetWriteDeadline configures the maximum amount of time that a synchronous
// Write operation can block for. A Write operation will unblock at the point
// that the read deadline is reached if no other condition (such as data sending
// or connection closure) happens first. If no deadline is configured, Write
// operations can potentially block indefinitely.
func (c *Conn) SetWriteDeadline(t time.Time) error { func (c *Conn) SetWriteDeadline(t time.Time) error {
// TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors... // TODO warn that this can block while waiting for the Conn actor to run, so don't call it from other actors...
phony.Block(c, func() { c.writeDeadline = &t }) phony.Block(c, func() { c.writeDeadline = &t })