github.com/pawelgaczynski/gain@v0.4.0-alpha.0.20230821120126-41f1e60a18da/interfaces.go (about)

     1  // Copyright (c) 2023 Paweł Gaczyński
     2  // Copyright (c) 2019 Andy Pan
     3  // Copyright (c) 2018 Joshua J Baker
     4  //
     5  // Licensed under the Apache License, Version 2.0 (the "License");
     6  // you may not use this file except in compliance with the License.
     7  // You may obtain a copy of the License at
     8  //
     9  //     http://www.apache.org/licenses/LICENSE-2.0
    10  //
    11  // Unless required by applicable law or agreed to in writing, software
    12  // distributed under the License is distributed on an "AS IS" BASIS,
    13  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14  // See the License for the specific language governing permissions and
    15  // limitations under the License.
    16  
    17  package gain
    18  
    19  import (
    20  	"io"
    21  	"net"
    22  	"time"
    23  )
    24  
    25  // Reader is an interface that consists of a number of methods for reading that Conn must implement.
    26  type Reader interface {
    27  	io.Reader
    28  	io.WriterTo
    29  
    30  	// Next returns a slice containing the next n bytes from the buffer,
    31  	// advancing the buffer as if the bytes had been returned by Read.
    32  	// If n is less or equal to 0, Next returns the entire buffer.
    33  	// The error is io.ErrShortBuffer if n is larger than the reader buffer size.
    34  	//
    35  	// Note that the []byte buf returned by Next() is not allowed to be passed to a new goroutine,
    36  	// as this []byte will be reused within event-loop.
    37  	// If you have to use buf in a new goroutine, then you need to make a copy of buf and pass this copy
    38  	// to that new goroutine.
    39  	Next(n int) (buf []byte, err error)
    40  
    41  	// Peek returns the next n bytes without advancing the reader. The bytes stop
    42  	// being valid at the next read call.
    43  	// If n is less or equal to 0, Peek returns the entire buffer.
    44  	//
    45  	// Note that the []byte buf returned by Peek() is not allowed to be passed to a new goroutine,
    46  	// as this []byte will be reused within event-loop.
    47  	// If you have to use buf in a new goroutine, then you need to make a copy of buf and pass this copy
    48  	// to that new goroutine.
    49  	Peek(n int) ([]byte, error)
    50  
    51  	// Discard skips the next n bytes, returning the number of bytes discarded.
    52  	//
    53  	// If n > 0 Discards tries to skip n bytes.
    54  	// If n == 0 Discards doesn't skip any bytes.
    55  	// If n < 0 Discards skips all buffered bytes.
    56  	Discard(n int) (int, error)
    57  
    58  	// InboundBuffered returns the number of bytes that can be read from the current buffer.
    59  	InboundBuffered() (n int)
    60  }
    61  
    62  // Writer is an interface that consists of a number of methods for writing that Conn must implement.
    63  type Writer interface {
    64  	io.Writer
    65  	io.ReaderFrom
    66  
    67  	// OutboundBuffered returns the number of bytes that can be read from the current buffer.
    68  	OutboundBuffered() (n int)
    69  }
    70  
    71  // Socket is an interface that represents a socket.
    72  type Socket interface {
    73  	// Fd returns underlying file descriptor.
    74  	Fd() int
    75  
    76  	// SetReadBuffer sets the size of the operating system's
    77  	// receive buffer associated with the connection.
    78  	SetReadBuffer(bytes int) error
    79  
    80  	// SetWriteBuffer sets the size of the operating system's
    81  	// transmit buffer associated with the connection.
    82  	SetWriteBuffer(bytes int) error
    83  	// SetLinger sets the behavior of Close on a connection which still
    84  	// has data waiting to be sent or to be acknowledged.
    85  	//
    86  	// If sec < 0 (the default), the operating system finishes sending the
    87  	// data in the background.
    88  	//
    89  	// If sec == 0, the operating system discards any unsent or
    90  	// unacknowledged data.
    91  	//
    92  	// If sec > 0, the data is sent in the background as with sec < 0. On
    93  	// some operating systems after sec seconds have elapsed any remaining
    94  	// unsent data may be discarded.
    95  	SetLinger(sec int) error
    96  
    97  	// SetKeepAlivePeriod tells operating system to send keep-alive messages on the connection
    98  	// and sets period between TCP keep-alive probes.
    99  	SetKeepAlivePeriod(d time.Duration) error
   100  
   101  	// SetNoDelay controls whether the operating system should delay
   102  	// packet transmission in hopes of sending fewer packets (Nagle's
   103  	// algorithm).
   104  	// The default is true (no delay), meaning that data is sent as soon as possible after a Write.
   105  	SetNoDelay(noDelay bool) error
   106  }
   107  
   108  // Conn is an interface representing a network connection.
   109  // Structures implementing it are not guaranteed to be thread-safe.
   110  // All write operations are asynchronous.
   111  type Conn interface {
   112  	Reader
   113  	Writer
   114  	Socket
   115  
   116  	// Context returns a user-defined context.
   117  	Context() (ctx interface{})
   118  
   119  	// SetContext sets a user-defined context.
   120  	SetContext(ctx interface{})
   121  
   122  	// LocalAddr is the connection's local socket address.
   123  	LocalAddr() (addr net.Addr)
   124  
   125  	// RemoteAddr is the connection's remote peer address.
   126  	RemoteAddr() (addr net.Addr)
   127  
   128  	// Close closes the current connection.
   129  	Close() error
   130  }